Skip to content

Code Standards

Code style guidelines for GreenThumb development.

Private repositories

The code repositories are private. These standards apply to everyone who contributes to them.

Python

Style Guide

  • Follow PEP 8
  • Use type hints for all functions
  • Write docstrings for public functions and classes
  • Use functions and classes for reusable code
  • Use the shared greenthumb package (greenthumb.crud, greenthumb.api.make_crud_router) instead of raw SQLAlchemy or hand-written CRUD routes.

No formatter or linter is enforced yet.

Example

def calculate_average(values: list[float]) -> float:
    """Calculate the average of a list of values.

    Args:
        values: List of numeric values

    Returns:
        The arithmetic mean of the values

    Raises:
        ValueError: If the list is empty
    """
    if not values:
        raise ValueError("Cannot calculate average of empty list")
    return sum(values) / len(values)

Naming Conventions

Type Convention Example
Functions snake_case get_sensor_data()
Classes PascalCase SensorModel
Constants UPPER_SNAKE MAX_RETRIES
Variables snake_case sensor_reading

SQL

  • Use UPPERCASE for SQL keywords
  • Use lowercase for table/column names
  • Use underscores for multi-word names
CREATE TABLE IF NOT EXISTS device_component (
    id_device_component INT GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY,
    id_device INT NOT NULL REFERENCES device(id_device)
);

Schema changes are made only in the database repository: schemas/ plus a dated file in migrations/.

Branches

Work lands on main. prod is what CI builds into images and what the devices run, so merging into prod deploys. In this docs repository, main is published. See CI/CD.

Commit Messages

Use conventional commit format:

type(scope): description

[optional body]

Types

Type Usage
feat New feature
fix Bug fix
docs Documentation changes
refactor Code refactoring
test Adding tests
chore Maintenance tasks
ci CI workflow changes

Append ! after the type for a breaking change (e.g. refactor!: drop a column).

Examples

feat(api): add endpoint for historical data
fix(sensors): handle AHT10 read timeout
docs(readme): update installation instructions

Project Structure

  • Keep related code together in modules
  • Use clear, descriptive file names
  • Separate concerns (data access, business logic, API)