engineering-standards

Engineering Standards

Conventions exist to remove decisions that do not matter, so attention goes to the ones that do. The specific choice matters far less than the consistency — three ways to do the same thing in one codebase is a defect even when all three work.

---

Code that reads well

Optimise for the reader. Code is read many more times than it is written, and usually by someone who has forgotten writing it.

• Names carry the meaning. daysUntilExpiry beats d. A good name removes the need for a comment.
• Comments explain why, never what. The code says what. A comment that restates the line is noise that will go stale; one that records the reason ("the provider returns 200 on failure, so we check the body") is permanent value.
• Functions do one thing at one level of abstraction. Mixing "orchestrate the checkout" with "format a date string" in one function forces the reader to change altitude mid-sentence.
• Early returns over nesting. Handle the failure and leave; keep the happy path unindented.
• Make illegal states unrepresentable. A discriminated union beats a struct with six optional fields and a comment explaining which combinations are valid.
• Explicit over clever. The clever line saves you a minute now and costs someone twenty later.
• Consistent error handling. One approach per codebase, applied everywhere.

Match the codebase you are in. Even where you would have chosen differently. Argue for the change in a PR of its own; do not smuggle it in alongside a feature.

---

Git workflow

Trunk-based, with short-lived branches, is right for the large majority of teams. Long-lived branches accumulate merge risk in direct proportion to their age.

main ──●──●──●──●──●──●──►   always deployable, protected
        \        /
         ●──●──●             feature branch: 1-3 days, then merged

Use Git Flow only if you genuinely ship versioned releases to customers who choose when to upgrade. For anything continuously deployed it is friction with no benefit.