Skip to main content

ChainAlign Coding Style Guide (v1.0)

Purpose​

To maintain clarity, consistency, and craftsmanship in every line of code — reflecting ChainAlign’s belief that good decisions require the same discipline as good code.

1 Core Principles​

  • Clarity Over Cleverness: Write code others (and future you) can read easily.
  • Explain the Why: Comments clarify intent and reasoning, not restate logic.
  • Consistency Across Layers: Frontend, backend, and AI engines must look and feel like one system.
  • Security by Default: Apply least-privilege, zero-trust, and data minimization principles.
  • Craft > Convention: When conventions hurt clarity, favor craft — but document why.

2 Foundation​

Use the Google Style Guide for your language (Python, TypeScript, etc.) as the base. Extend it with Axolo-style operational standards — including testing, version control, and API hygiene.

3 Commenting Standards​

Goal: Explain why, not what.

  • Use comments for decisions, assumptions, trade-offs, and edge cases.
  • Keep them concise and update them alongside code changes.
  • Use docstrings for functions and classes:
def run_simulation(params: Dict) -> SimulationResult:
    """
    Runs a Monte Carlo simulation to evaluate plan feasibility.

    Args:
        params: Model configuration and input variables.
    Returns:
        SimulationResult object with risk metrics and confidence intervals.

    Why:
        Isolates probabilistic logic for reuse in constraint testing.
    """

Avoid redundant comments:

// increment counter by 1  ❌

4. API Design Consistency​

Align APIs with ChainAlign’s architecture and PRD principles of clarity, auditability, and compliance.

  • Style: RESTful preferred; GraphQL only when query flexibility is critical.
  • Naming: Plural nouns (/plans, /decisions), lowercase, hierarchical (/api/v1/...).
  • Status Codes: Use canonical HTTP codes (200, 201, 400, 404, 500).
  • Error Format:
{ "error": { "code": "INVALID_INPUT", "message": "Forecast ID missing" } }
  • Security: Enforce OAuth 2.0 or Firebase Auth. Never expose tokens in URLs.
  • Documentation: Maintain OpenAPI/Swagger specs for each service.
  • Versioning: Prefix all endpoints with /v1/ and log deprecations.

5. Naming & Structure​

General​

  • Descriptive names: calculate_forecast_error, not calcErr.
  • Casing conventions:
    • Python → snake_case
    • TypeScript/JS → camelCase
    • Classes → PascalCase
  • Avoid ambiguous abbreviations unless industry-standard (MAPE, SOP).

File Layout​

Follow ChainAlign’s modular microservice model:

/ai-engines/
    /insight-engine/
    /constraint-engine/
    /consensus-engine/
    /stt-service/

Each module must include:

  • README.md – purpose, data flow, API contract
  • tests/ – comprehensive coverage
  • config/ – environment docs
  • main.py or index.ts entry point

6. Testing & Quality​

  • Frameworks:
    • Python → pytest
    • JS/TS → jest
  • Coverage Target: ≥80%
  • Types of Tests: Unit, integration, regression
  • Naming Convention: test_functionName_scenario_expectedResult
  • CI Integration: Enforce linting, typing, and tests pre-merge.

7. Version Control (Git)​

  • Branch Naming:
    • feature/ai-insight-engine
    • bugfix/constraint-loop
    • chore/docs-update
  • Commit Message Format:
[AI] Add Monte Carlo confidence interval calculation
  • Pull Requests:
    • Small, focused, and descriptive
    • Include “Why this change?” summary
    • At least one reviewer required

8. Error Handling & Logging​

  • Custom Errors: Use descriptive exception classes.
  • No Silent Failures: Log context-rich messages.
  • Structured Logging (JSON):
{
  "service": "insight-engine",
  "event": "simulation_run",
  "user": "uid_123",
  "timestamp": "2025-10-14T12:00:00Z",
  "status": "success"
}
  • Sensitive Data: Never log tokens, passwords, or customer data.

9. Documentation & Readability​

Every module should be explorable by a new engineer in <15 minutes.

Each directory must include a clear README.md outlining:

  • Purpose and inputs/outputs
  • Dependencies
  • Key design decisions and rationale

Follow the ChainAlign brand tone — precise, transparent, intelligently confident.

10. Cultural Alignment​

Code is culture. Follow ChainAlign’s four cultural filters:

  • Builders Over Talkers: Show your work in commits, not slides.
  • Craft Over Career: Depth and precision are leadership traits.
  • Team Success Over Ego: Reviews are collaborative, not adversarial.
  • Optimistic Experimenters: “Let’s try” beats “That won’t work.”

11. Tooling Standards​

  • Linters: ESLint, Flake8, Prettier
  • Type Checking: mypy, TypeScript strict mode
  • Secrets Management: GCP Secrets Manager / Vault
  • Dependencies: Locked via requirements.txt / package-lock.json
  • Containerization: Podman for all services; consistent Dockerfile templates
  • Docs Generation: Auto-generated from Swagger/OpenAPI

12. Style Enforcement​

  • Pre-commit hooks must check linting, typing, and tests.
  • PR merge is blocked if:
    • Lint errors exist
    • Tests fail
    • API spec not updated after endpoint changes
  • Maintain a shared .editorconfig for tabs, indentation, and line endings.

13. Example Code Philosophy​

Bad:

x = run(params)
if x: print("ok")

Good:

result = run_simulation(model_params)
if result.is_successful():
    logger.info("Simulation completed successfully.")

14. Governance​

Maintainer: Engineering Lead / Codecraft Council

Review Cycle: Quarterly or after major architectural changes

Scope: All services, including AI Engines, Web Client, and Infrastructure

ChainAlign’s code reflects its culture — transparent logic, visible reasoning, and disciplined craftsmanship.