coding-standardslisted

# Coding Standards Code is read far more often than it is written, and it outlives the session, ticket, or conversation that produced it. These are the language-agnostic rules for writing code so that a future reader — human or agent, with none of today's context — can trust what they see without a second source. ## Quick-scan | Concern | Rule | |---------|------| | Module purpose | One doc-header per module: state its purpose, key inputs, and gotchas. The single place a reader learns "why this exists." | | Inline comments | Only for the non-obvious "why." Never narrate what the code already says. | | Rationale placement | Each rationale lives in exactly one place. A second file references it; it never repeats it. | | Input documentation | Lives in the language's native doc mechanism (see `reference.md`), never duplicated in a plain comment beside it. | | Dead code | Delete it. Git history is the record, not a comment. | | Temporal / attribution comments | None. No "added by X on date," no changelog-in-comment — `git blame` and the commit message already own that. | | Tooling / plan traces | Zero. No task IDs, AC numbers, Finding/Risk labels, "generated by," or any pointer to the process that produced the code. | | Style | Consistent within a module and a repo. Match the existing pattern before introducing a new one. | | Length vs. redundancy | Length is not the enemy; redundancy is. A comment earns its line only if it says something the code cannot. | ## The doc-header