Style guide - Capsize-Games/airunner GitHub Wiki

Python Style Guide

This Python style guide outlines best practices for code consistency, readability, and maintainability. All developers and bots should adhere to this guide.

1. Adherence to PEP 8

  • PEP 8 Compliance: Follow PEP 8 (https://www.python.org/dev/peps/pep-0008/) standards strictly.
  • Line Length: Limit lines to 79 characters.
  • Indentation: Use 4 spaces per indentation level, never tabs.
  • Whitespace: Avoid unnecessary whitespace inside parentheses, brackets, or braces.

2. Naming Conventions

  • Variables: Use snake_case (e.g., user_name).
  • Functions: Use snake_case (e.g., calculate_sum).
  • Classes: Use PascalCase (e.g., DataProcessor).
  • Constants: Use uppercase with underscores (e.g., MAX_LIMIT).

3. Imports

  • Group imports in the following order:
    1. Standard library imports
    2. Third-party library imports
    3. Local application imports
  • Separate each group with a blank line.
  • Use absolute imports whenever possible.

4. Comments and Docstrings

  • Inline Comments: Keep inline comments minimal and to the point.
  • Docstrings:
    • Include docstrings for all modules, classes, methods, and functions.
    • Use triple-double quotes for docstrings ("""This is a docstring.""").
    • Follow the Google-style format for detailed descriptions.

5. Code Structure

  • Limit function length to 20 lines or less whenever practical.
  • Limit class length to fewer than 200 lines.
  • Maintain a logical order:
    • Class attributes first, then methods.
    • Public methods first, followed by protected (_) and private (__) methods.

6. Error Handling

  • Use specific exceptions (ValueError, KeyError) rather than generic ones (Exception).
  • Clearly document exceptions in function docstrings.

7. Readability and Simplicity

  • Write clear, self-explanatory code.
  • Prefer list comprehensions and generator expressions over loops where appropriate.
  • Avoid overly clever or complex expressions.

8. Testing

  • Include unit tests for all modules and key functions.
  • Place tests in a separate tests/ directory.
  • Follow consistent naming: test files as test_module.py and test methods as test_functionality().

9. File and Directory Structure

  • Follow a consistent project structure: 
    project/
├── project_name/
│   ├── __init__.py
│   ├── module1.py
│   └── module2.py
├── tests/
│   └── test_module1.py
├── docs/
└── README.md

10. Version Control

  • Write clear and descriptive commit messages.
  • Follow the Git flow model (feature branches, merge requests, main/develop branches).

10. Testing Guidelines

  • Ensure all classes and methods are covered by unit tests.
  • Place tests in a separate tests/ directory within the corresponding module.
  • Use descriptive test names that clearly indicate the purpose of the test.
  • Mock external dependencies to isolate the functionality being tested.

11. Documentation Updates

  • Update the wiki to reflect changes in the codebase.
  • Include examples and usage instructions for new or modified classes and methods.
  • Ensure consistency in terminology and formatting across all documentation.

Adhering to these guidelines will ensure code clarity, maintainability, and collaborative efficiency across your team and automated systems.