Key Takeaways — Chapter 34: Writing for Computer Science

The summary card. Use it to re-ground before the quiz, or to review weeks later.

The one idea

Almost everything a software engineer writes is aimed at a person, and the two highest-stakes genres share one move: separate the work from the person. In a code review, you critique the code, not the coder. In a postmortem, you debug the system, not the human. It's the same idea seen twice, and it's not politeness—it's the only framing that produces the outcome you actually want (better code, fewer outages), because aiming at the person produces defensiveness, hidden mistakes, and engineers who stop telling you the truth.

🚪 Threshold concept: Before you cross it, the code feels like an extension of the person who wrote it, so a flaw in the code is a judgment on them—and an outage has a culprit. After, you see the code as a fact about some lines of text two peers can improve together, and an outage as a property of a system that let human error through. You stop writing "you forgot the empty case" and start writing "this returns None on empty input, line 14"; you stop writing "Sam should have tested it" and start writing "no test exercised the default." The first version is a guess about a person that costs trust; the second is true, specific, and fixable.

The everyday writing of code work

The core moves

• Code-review comments: candor without cruelty. Name the exact line and behavior (specificity is kindness), describe what the code does, offer a path forward, ask genuine questions, praise what's good, and label weight (nit: vs. blocking). A reviewer who waves through real bugs fails as badly as a cruel one—aim hard objections at the code.
• PR descriptions give what the diff can't. The diff shows the what; you supply the why (you can't judge an implementation without knowing its intent) and the how to test (the most-skipped, most-valuable part—it lets the reviewer verify, not just inspect). Keep PRs small enough that the what fits in two sentences.
• Bug reports are reproducible and actionable, not emotional. A minimal repro is the single most valuable thing—and minimizing it is itself debugging. State expected vs. actual (a bug is the gap between them) and the environment. "Doesn't work, ASAP" is a feeling, not a fix.
• Acceptance criteria are the contract for "done." Testable Given-When-Then conditions, covering the empty case, the error case, and a concrete number ("under 500 ms at p95," not "fast"). Writing the edge-case criterion forces the product decision to be made on purpose.
• A design doc is thinking on paper before building. State the problem (quantified) before any solution; weigh the alternatives you rejected and why. A flaw caught on paper costs an afternoon; the same flaw caught in week three costs the weeks built on top of it. For non-trivial work, the doc is the engineering.
• A blameless postmortem turns failure into system improvement. Neutral timeline (facts) separate from root cause (analysis); the root cause is the system condition reached by asking "why was it possible?"; action items change the system and have owners and dates—never "be more careful." Naming a person and blaming a person are different acts; do the first, never the second.

Why blamelessness is mechanical, not merely kind

A blame-seeking postmortem teaches engineers to hide mistakes, omit damaging details, and stay quiet during the next incident—degrading the information every future postmortem needs, so the same failure recurs. Blamelessness trades the satisfaction of finding a culprit for the truthful information that actually prevents recurrence. It's self-interest, not softness.

The test to apply before you send anything

For a review comment or a postmortem: could the person at the center read it and feel informed and supported, not accused—while it still says the true, hard thing about the code or the system? For a PR, a bug report, or acceptance criteria: could the reader act on it—review, reproduce, build—without coming back to ask you a single question?

If no, you aimed at the person instead of the work, or you wrote for yourself (venting, looking thorough) instead of for the reader who has to act.

If you remember three things

1. Critique the code, not the coder; debug the system, not the human — one move, two genres, the heart of technical collaboration.
2. Tell the reader what they need to act — the why and how to test for a reviewer; a reproducible expected-vs-actual for a fixer; testable criteria for a builder.
3. The principles don't change between fields; only the conventions do — these are the same audience, structure, and clarity skills the book has taught throughout, wearing software's costumes.

Themes surfaced: #2 audience-is-everything (central—every genre is aimed at a specific reader who must act: a reviewer, a fixer, a frightened on-call engineer) · #5 structure-serves-the-reader (the PR's what/why/how, the bug report's fields, the postmortem's timeline-then-analysis all order information by the reader's need) · #1 writing-is-thinking (a design doc surfaces design flaws on paper; minimizing a bug repro locates the cause; writing an acceptance criterion forces a product decision) · #6 every-sentence-earns-its-place (cut the venting from a review comment, the marketing from release notes, the blame from a postmortem—each is noise that buries the signal).

Threshold concept: In a code review you critique the code, not the coder; in a postmortem you debug the system, not the human—one move, seen twice.

Back to: Chapter 34 · Exercises · Quiz · Further Reading