AR8: Engineering standards and code review
Standards worth having
🎯You'll be able to
Write a short set of coding standards in which each rule has a reason, an example and a way it's checked.
🏠The everyday picture
A busy kitchen has a few firm rules: label and date everything in the fridge, wash hands after raw meat, call "behind" when passing. Each prevents a real problem. Nobody needs fifty rules about how to hold a spoon.
📘What it really is
- A standard is a rule the team agrees to follow, so code is safe and familiar to everyone who changes it.
-
Few and important: rules that prevent real harm (secrets in code, hidden errors, tangled modules) matter more than style preferences, which a formatter can settle.
-
Each rule has: an ID, the rule in one line, why it exists (a sentence a new teammate would accept), an example, and how it's checked (a tool, or review).
-
Write the reason from evidence: an incident, a cost, a bug. Rules without reasons get ignored.
- Version and date the document, so people know which rules apply and when they were last reviewed.
📝A worked example
Input: the starter's standards: "Write clean code. Use good names. Test your code. Don't commit secrets."
Steps:
- "Don't commit secrets" becomes R1: No secrets in code. Why: anyone who can read the repository can use them. Checked by: lint
no-secrets. Example:process.env.PAYMENTS_API_KEY. - "Write clean code" is too vague; replace with specific rules, such as R3 (errors handled, not hidden) and R5 (functions under 40 lines).
- "Use good names" becomes R2 with an example, checked by review.
- Add "Version: 1.0" and "Last reviewed".
Expected output: a document of eight to twelve rules, each with why, an example and how it's checked.
🌍Where it's used
- Large companies publish style and engineering guides with reasons for each rule.
- Open-source projects keep a contributing guide with the rules for pull requests.
- Regulated industries require documented secure coding standards.
📝Case scenario
A team's 40-page style guide covered brace positions and blank lines, and said nothing about secrets. Nobody read it. A key was committed and abused within hours. A one-page set of ten rules, starting with secrets and error handling, became the guide people actually used.
🖱️Try it
Turn two vague rules from any guide you know ("be clean", "be safe") into specific rules with a reason, an example and how they're checked. Success: someone could tell whether code follows them.
⚠️Common mistakes
- Rules without reasons. Sign: people argue about every rule. Fix: a "Why" from evidence.
- Too many rules. Sign: nobody can remember them. Fix: few rules that prevent real harm.
- Style debates in review. Sign: comments about spacing. Fix: a formatter settles style automatically.
🛠️For your project
Project 3's test 1 checks at least eight rules in docs/standards.md, each with Why, Checked by and a code example.
✅Quick check
What should every rule in a standards document include?
Show the answer
An ID, the rule, why it exists, an example and how it's checked.
Why should style questions be settled by a formatter rather than by review?
Show the answer
They're preferences, and a tool settles them without arguments, leaving review for what matters.