Coding Values and Engineering Priorities

Date: 2026-02-08 Status: Draft

Use these values to guide implementation decisions and code review.

1. Clarity Over Cleverness

• Code should be understandable by the next maintainer.
• Prefer explicit naming and boundaries over implicit behavior.

2. Contracts First

• Define or reference contracts before implementation.
• Keep request/response/event schemas explicit and versioned.

3. Testability by Design

• Unit tests for pure logic and boundary handling.
• Integration tests for service contracts and persistence behavior.
• Regression tests for bugs that escaped once.

4. Reliable Async Work

• Idempotent handlers for retried jobs/events.
• Explicit timeout, retry, and dead-letter behavior.
• Structured status model for queued/running/succeeded/partial/failed states.

5. Scalability and Performance

• Bound expensive operations and pagination.
• Prefer batch processing and streaming where practical.
• Define SLO-aligned latency targets for critical paths.

6. Encapsulation and Boundaries

• Keep provider-specific logic behind connector boundaries.
• Keep domain logic out of transport/framework layers.
• Limit cross-service coupling through stable contracts.

7. Observability and Auditability

• Emit actionable logs with identifiers.
• Capture metrics and audit events for critical operations.
• Never log secrets.

8. Security as a Default

• Least privilege for access and runtime roles.
• Secure secret storage and rotation mechanisms.
• Threat/abuse cases considered during design.