Coding standards

These standards give our teams a shared baseline. Customer or framework conventions override them where they conflict; if so, document the choice in the project README.

General principles

  1. Prefer clarity over cleverness.
  2. Keep functions small and single-purpose.
  3. Write code for the next reader. Comments explain why, not what.
  4. Automate formatting; do not debate it in review.
  5. Fail loudly: handle errors explicitly and log with context.

Languages and tools

Language Formatter Linter Test framework
Python black ruff pytest
TypeScript prettier eslint jest
Java google-java-format checkstyle JUnit
SQL sqlfluff sqlfluff database tests

Security rules

  • Never commit secrets. Use the secret store provided for the project.
  • Validate all input; use parameterised queries.
  • Use the approved authentication libraries. Applications must support multi-factor authentication and passwords of at least 14 characters, to align with POL-IT-003.
  • Log access to personal or customer data, but never log the data itself.
  • Keep dependencies updated; critical vulnerabilities must be fixed before release, see Release process.

Naming and structure

# Good: names say what they mean
def calculate_invoice_total(line_items: list[LineItem]) -> Decimal:
    return sum(item.amount for item in line_items)
  • Use meaningful names; avoid abbreviations except those in the glossary.
  • Keep one logical module per file.
  • Put configuration in environment variables or configuration files, not in code.

Testing

Every change needs tests proportionate to its risk. Aim for fast unit tests, a smaller set of integration tests, and a few end-to-end tests of critical paths. See the definition of done.

Data handling

Customer data remains in the environments agreed in the contract. For instance, Orion Energy data must stay in the US (see Orion Energy), and Stellar Health data needs extra protections (see Stellar Health). Production data must not be copied to laptops or development environments unless it is anonymised.

Reviews

All changes follow the Code review rules. Reviewers will ask for changes that violate this page.

Evolving the standards

Suggest changes by raising a pull request against the engineering handbook or by speaking to Isha Patel (Solutions Architect) or Daniel Okafor (CTO).

Owner: Isha Patel - Last updated: 2026-07-09