forge-coding-standards

Coding standards

Loaded on every build step. Not advice — the reason the project still looks like one project by phase eight, when the code was written weeks apart across different sessions.

Overridable, but only by a recorded decision that says which rule and why. The security floor is the exception; it is not overridable at all.

Write for the person who reads it next

• Names say what a thing is, not what type it is. pending_invoices, not list2.
• A function does one thing at one level of abstraction. If the name needs "and", split it.
• Comments say why, never what. The code already says what. A comment restating the line above it is noise; a comment explaining the constraint that forced an odd shape is the most valuable line in the file.
• Match the surrounding code. A file with one clever idiom in it reads worse than a plain file.

Errors

• Fail on the specific exception, never a bare catch-all.
• An error message says what failed, what was expected, and what to do next.
• Never swallow an error to make a test pass. Never log-and-continue where the caller needed to know.

Structure

• One responsibility per module. When a file needs "and" to describe it, it is two files.
• Dependencies point inward: the thing that changes often depends on the thing that does not.
• No configuration in code. No magic numbers — a named constant says what the number means.

Tests

• A test names the behaviour it protects, not the function it calls: test_a_write_with_no_decision_is_blocked, not test_governor_2.
• Every test must be able to fail. A trailing or True slipped through here once and the test looked green for weeks.
• Test the boundary and the failure, not only the happy path. The happy path is the case that was already working.
• Prefer a real filesystem or a real repository over a mock wherever it is cheap. A mock proves the code calls what you expected, not that it works.

What to do when the standards and the request conflict