Coding conventions

This document outlines the coding conventions and best practices to be followed when contributing to the SCIMBA project. Adhering to these guidelines will help maintain code quality, readability, and consistency across the codebase.

Naming

  • Use descriptive and meaningful names for variables, functions, classes, and modules.

  • Follow the PEP 8 naming conventions: use snake_case for variables and functions, PascalCase for classes, and UPPER_CASE for constants…

The N rule is automatically checked and fixed by ruff in the pre-commit hooks.

Code formatting

  • Follow PEP 8 guidelines for code formatting, including indentation, line length (maximum 88 characters), and spacing.

  • Use blank lines to separate functions and classes, and to separate sections of code within functions.

The E, F and W rules are automatically checked and fixed by ruff in the pre-commit hooks.

Type hints

Use type hints to indicate the expected types of function arguments and return values. Comply with Python 3.10+ type hints:

  • Use list[str] instead of List[str], dict[str, int] instead of Dict[str, int], etc.

  • Use str | None instead of Optional[str], int | float instead of Union[int, float], etc.

The UP rule is automatically checked and fixed by ruff in the pre-commit hooks.

Comments and documentation

  • Use docstrings to document all public modules, functions, classes, and methods.

  • Use inline comments sparingly and only when necessary to explain complex or non-obvious code.

See Documenting for more details.

Imports

  • Group imports into three sections: standard library imports, third-party imports, and local application/library imports. Each group should be separated by a blank line.

  • Avoid wildcard imports (e.g., from module import *).

The I rule is automatically checked and fixed by ruff in the pre-commit hooks.

Error handling

  • Use exceptions for error handling. Avoid using return codes to indicate errors.

  • Catch specific exceptions rather than using a bare except clause.

Testing

  • Write unit tests for all new features and bug fixes. Use pytest as the testing framework.

  • Ensure that tests are isolated and do not depend on external resources or the state of other tests.

See Testing for more details.

Version control

  • Write clear and concise commit messages that describe the changes made.

  • Use branches for new features and bug fixes, and merge them into the main branch only after thorough review and testing.

Code reviews

  • Participate in code reviews to ensure code quality and share knowledge among team members.

  • Provide constructive feedback and be open to receiving feedback on your own code.