Software Engineering · Chapter 4 of 31
Code, review and the 9%
Testing appears in 9% of postings because it is assumed. Here is what is actually being assessed.
The low testing number is not licence to skip it — it means describing your testing discipline is not a differentiator. What is assessed is judgement: what deserves a test, what deserves a type, and what deserves neither.
What good judgement looks like
- Test behaviour, not implementation. A test that breaks when you refactor without changing behaviour is a liability, and a suite full of them is why teams stop refactoring.
- Test at the cheapest level that gives confidence. A pyramid is a heuristic, not a rule; some systems are genuinely better served by a thick integration layer.
- Prefer making states unrepresentable over testing that they do not occur. A type that cannot express an invalid combination removes a class of test entirely.
- Know what you are not testing and say so. ‘We have no coverage of the payment retry path and that is our biggest risk’ is a strong thing to be able to say.
Code review, which is 33% and is really about influence
Review is where engineering culture is actually set. The habits worth having: separate “this is wrong” from “I would have done it differently”, and say which you mean; ask a question rather than issue an instruction when you are not certain; approve with comments rather than blocking on preference; and review promptly, because review latency is usually the largest single component of lead time and it is entirely within your control.
On AI-assisted code, which 89% of postings now touch
The position that lands: specific about where you use it and where you do not. “I use it for tests, boilerplate and unfamiliar APIs, and I read anything touching auth, money or concurrency line by line” is a real answer.
The two failing answers are “I don't use it”, which reads as incuriosity in a market where 89% of postings mention it, and unqualified enthusiasm, which reads as someone who has not yet been burned by a confidently wrong suggestion in a subtle place.
What actually makes code maintainable
Most code-quality advice is aesthetic and reversible. A small number of properties genuinely predict whether a codebase is still workable in three years, and they are worth being able to name and defend.
| Property | Why it survives | The failure it prevents |
|---|---|---|
| One obvious place for each thing | New people find it; nobody writes a second one | The same logic implemented three times, drifting apart, two of them wrong |
| Explicit dependencies | You can see what a module needs by reading its signature | The change that breaks something with no visible relationship to it |
| Errors that carry context | The message names what was being attempted with what input | Twenty minutes reading code to work out what the log line meant |
| Narrow interfaces | A caller can only do the small set of things you intended | Every internal detail becoming load-bearing because someone reached in |
| Tests at the seam, not the unit | They survive refactoring, because they assert behaviour | A test suite that must be rewritten every time you improve the implementation — which teaches people not to refactor |
That last row is the most consequential and the least followed. A test that asserts implementation detail is a tax on every future change. Teams end up with a suite that goes red on correct refactors, and the lesson everyone quietly learns is to stop refactoring. The test suite then causes the rot it was meant to prevent.
Code review: what to say and what to leave alone
- Separate the blocking from the optional, explicitly. Prefix comments so the author knows what must change. Most review friction is authors guessing which comments are requirements.
- Block on: correctness, security, data loss, an interface you cannot take back, and anything that will page someone at three in the morning.
- Do not block on: naming you would have done differently, structure that is merely not your preference, or anything a formatter should own. If a machine can decide it, a human should not be spending review capacity on it.
- Ask rather than assert when you might be wrong. ‘What happens if this is empty?’ is better than ‘this breaks on empty’, and costs nothing when you are right.
- Review the diff you were given. Requesting an unrelated refactor in someone else's change is the most common way review becomes something people avoid.
The two review comments that catch the most real bugs
“What happens the second time this runs?” Retries, redeliveries and double-clicks are everywhere, and non-idempotent handlers are the most common serious defect that passes review.
“What happens if this is empty, null, or enormous?” The three inputs nobody tests, and the three that appear in production within a month.
Both are questions, both take five seconds to write, and neither requires understanding the whole change — which is why they work on reviews you are not the right person for.
And a rule for the review culture rather than the review: if you find yourself leaving the same comment repeatedly, it is not a review comment. It is a lint rule, a type, or a piece of documentation you have not written yet.
Check yourself