bertsatlas/principles.md

Coding principles

• Make the code say what the system is doing. A reader should not need a comment to discover the important behavior.
• Keep domain behavior visible. Do not hide meaningful actions behind vague, generalized operations.
• Name state transitions after the exact domain change they perform. Prefer a specific transition over a generic update.
• Introduce abstractions only when the shared idea is genuinely independent of the domain. Similar-looking code is not enough reason to generalize it.
• Scope each interface to one kind of consumer. A type may implement several interfaces, but callers should only see the operations relevant to them.
• Keep repository operations small, explicit, and easy to verify. Query names and inputs should make their intent clear without a separate explanation.
• Use comments to record constraints that cannot be expressed in code. Do not use comments to compensate for unclear names, mixed responsibilities, or complex control flow.
• Keep familiar terminology when it is already precise. Rename something only when the new name adds material clarity.
• Prefer direct composition of simple operations over a single method that combines unrelated responsibilities.
• Keep design proportional to the problem. Add structure when it clarifies behavior, not merely to make the code look more abstract or uniform.
• Use configuration only for secrets or values that genuinely vary between environments. Keep stable values in code, preferably as constants.
• Never assume an internal infrastructure artifact exists, including container image tags, deployment resources, topics, subscriptions, service accounts, or permissions. Verify it against the owning system before referencing or changing it; if it cannot be verified, stop and state the dependency explicitly.