Naming of things

Warning

🚧 This section is still in active development and is subject to changes 🚧

Philosophy and ideals

How we name things, both internally and user-facing, will be:

  • Simple: Keep the vocabulary simple and easy to understand
  • Composable: Can be combined with other names to imply intent
  • Predictable: Easy to guess and reason on, without needing to look up documentation
  • Reusable: Can be used across multiple contexts
  • Consistent: Remains the same across different contexts
  • Align with existing conventions: Follow widely-established standards and conventions

User-facing content

The below naming scheme only applies to file paths, functions, URLS, API endpoints, and command line interfaces that are exposed to or associated with user-facing content. It does not apply to internal content; see section below on naming for developer-facing content.

Composing names

For each software product, we aim to compose names based on the objects we and our users interact with as well as the actions taken on those objects, as well as any identifiers (for instance, a specific project or data object). These objects and actions are inspired by and align with the “core” language of working with data called CRUD (Create Read Update Delete), common naming schemes used in REST API applications or services (such as Github), as well as by the vocabulary of the HTTP verbs (GET, POST, PUT, PATCH, and DELETE).

To name things, we try to combine object names first, followed by the action, with a natural hierarchy of “offspring” to the objects (for instance, a project has one or more databases but a database can’t have a project). Based on these principles, we can derive a naming scheme. In the scheme, objects and actions are ordered, with names occurring first acting as a “parent” to later names. The names are separated by a symbol based on its context:

  • _ for Python function names.
  • - for file path names.
  • / for URLs and web API endpoint names (a / always begins each URL to act as a root, but never ends a URL).
  • for command line interface names.

Developer-facing (internal) content

Python

Following the same naming schemes for CRUD, HTTP verbs, and common REST API endpoints, these are some guidelines on the general words to use for actions and objects. We aim to keep the number of objects limited, with a sufficient set of actions to interact with the objects. For instance, some actions and objects could be:

  • Actions: list, edit, delete, create, extract, verify, read, write, to
  • Objects: array (analogous to non-nested Lists and Sets in base Python and Series in Pandas or Polars), lists (analogous to nested Lists, Tuples, and Dictionaries in Python or Tables in SQL), files, classes

Some general guidelines when naming things in Python:

Functions

  • Use snake_case().
  • Prefer a single action verb for functions: action().
  • Use the arguments to specify the object: action(object=).
  • If necessary, include the object in the name following the pattern action_object().
  • If the object is in the name, prefer the plural form of the object if the function could return multiple items of an object.
  • If the object is in the name, prefer a single generic object name rather than multiple specific names: read_csv() rather than read_csv_file() or upload_file() rather than upload_csv_file() (uploading isn’t depending on file extension, while reading is)

Methods

  • Includes everything from the functions
  • Prefer action verbs only: ClassName.action().
  • Avoid using object names, unless it makes the action clearer.

Classes

  • Use PascalCase.
  • Use objects as the class name: Object.
  • Prefer the plural form of the object name: Objects.
  • Prefer a single object name (Objects) rather than multiple (TwoObjects).

Variables

  • Use snake_case.
  • Prefer a plural form for objects if they could contain more than one item.
  • Use singular form only if the object must only contain one item.
  • If an action name is necessary, prefix action verb in the past tense: actioned_object.

Arguments

  • Includes everything from variables above
  • Prefer single object names rather than actions: object.
  • Prefer the plural form: objects.
  • Use singular form only if the function or method input must only contain one item.