Skip to main content

Style Guidelines

We start with guidelines for Python, since this is the most used language in our project, but similar ideas apply to other languages (Go, C, ...)

General Principles​

  • Readability: Code should be easy to read and understand. Prioritize clarity over cleverness.
  • Consistency: Follow the same conventions throughout the project to maintain consistency.
  • Simplicity: Write simple, straightforward code. Avoid unnecessary complexity.
  • Try to adhere to standards: use PEP 8, the official Python style guide
note

For other languages please use Google styleguides

Code Layout​

Indentation​

  • Use 4 spaces per indentation level. Do not use tabs.

Blank Lines​

  • Use blank lines to separate functions, classes, and blocks of code inside functions.
    • 2 blank lines between top-level definitions (e.g., functions or classes).
    • 1 blank line between methods inside a class.

Imports​

  • Place all imports at the top of the file, just after any module comments and docstrings.
  • Group imports in the following order:
    1. Standard library imports.
    2. Related third-party imports.
    3. Local application/library-specific imports.
  • Use absolute imports whenever possible.
  • Import specific classes or functions rather than importing the entire module (e.g., from module import Class instead of import module).

Some Naming Conventions​

Variables and Functions​

  • Use descriptive names for variables and functions that clearly convey their purpose.
  • Use snake_case (lowercase words separated by underscores) for variable, function, and method names.
    • Example: my_variable, calculate_sum()

Classes​

  • Use CamelCase (capitalize the first letter of each word) for class names.
    • Example: MyClass, DataProcessor

Constants​

  • Use UPPER_CASE (all uppercase letters with underscores between words) for constants.
    • Example: MAX_VALUE, DEFAULT_TIMEOUT

Linting​

We don't want to manually format the code, so make sure a project has automated liners and type checkers configured. We'll provide a template project that includes all necessary configurations.

Documentation​

Linting tools will be checking for documentation as well. Here are the recommendations:

Comments​

  • Write comments that explain why something is done, not just what is done.
  • Use inline comments sparingly and only when the code is not self-explanatory.
    • Place inline comments on the same line as the statement they refer to

Docstrings​

  • Use docstrings to describe the purpose of modules, files and classes. For public facing libraries, also describe functions.

  • Follow PEP 257 conventions for writing docstrings.

    • Single-line docstrings: Use triple double quotes, and keep the closing quotes on the same line.

      • Example: """Return the sum of x and y."""

    • Multi-line docstrings: Begin with a one-line summary, followed by a blank line, then a more detailed description if necessary.

      • Example:

        """
        Calculate the sum of x and y.

        This function adds the two numbers provided as arguments
        and returns the result.
        """

Testing​

  • Try to write unit tests for all new features and bug fixes.
  • Use meaningful test names that describe the behavior being tested.
  • Run all tests before submitting changes to ensure they pass.
  • Make sure tests are included into an automated pipeline that runs on commit

Version Control​

see Project management and workflow using GitLab for general recommendations

Commit Messages​

  • Write clear and concise commit messages.
  • Use the imperative mood ("Add", "Fix", "Update") in the commit message title.
  • Include a brief summary of the changes in the body of the commit message, if necessary.
  1. Clean Code: A Handbook of Agile Software Craftsmanship by Robert Martin
  2. The Pragmatic Programmer by Andy Hunt and Dave Thomas.
  3. Refactoring: Improving the Design of Existing Code by Martin Fowley
  4. Software Engineering at Google: Lessons Learned from Programming Over Time: by Titus Winters et al.