Say It in Code: Comments & Formatting
Most comments are apologies for code that failed to speak — delete the narrator and let the code say it.
The idea
Here is the uncomfortable claim of Chapter 4: most comments exist because the code failed to say something, and instead of fixing the code, someone wrote a note beside it. A comment above a gnarly boolean is not documentation, it is an apology. And unlike code, comments never run, so nothing forces them to stay true. They rot quietly, and a comment that lies sends the next reader confidently in the wrong direction.
The move is to express, not annotate. A comment explaining a condition becomes a function named for what it checks. A comment explaining a magic value becomes a named constant. A comment labelling a section of a long function becomes an extracted function whose name is the label. The comment is not so much deleted as promoted into a name, where the compiler and your tests keep it honest forever.
This is not a ban on comments. A few genuinely earn their keep: intent, warnings, amplification of something load-bearing, legal headers, honest TODOs. What they share is that they say what the code cannot say, the why and the danger, not the what. Commented-out code is the one thing with no defence at all. You have version control; the delete key is the archive.
Formatting sounds like tidiness but it is really communication. Blank lines are paragraph breaks, vertical distance encodes relatedness, and a caller belongs directly above the thing it calls. A well shaped file survives the squint test: zoom out until the text blurs and the blocks still tell you where things live. And one shared team style applied consistently beats your personal taste applied brilliantly.
The bench — 4 exercises
Comment Triage
Take a working file carpeted with sixty comments and decide, one by one, which are keeps, which are deletions, and which should become code. Triage is the skill; the edits are just the follow-through.
- Pick any real file you own with heavy comments, or write one: mix redundant narration, a journal header, mandated doc noise, position markers, one stale comment that contradicts the code, and a few blocks of commented-out code.
- Make a worksheet with one row per comment: keep, delete, or replace-with-code, plus a one-word reason (redundant, misleading, journal, noise, commented-out, intent, warning).
- Write or keep a small characterization test suite that pins current behavior before you touch anything.
- Execute the sentence: delete the deletions, perform the replacements, keep only the handful that say something code cannot.
- Re-run the tests and confirm the stale comment's claim lost to the code's actual behavior.
hint
When unsure, ask one question: could the code be made to say this? If yes it is a replace, not a keep, even when the comment is accurate and well written.
hint
Detect commented-out code by reading each comment body as code: if it lexes, it goes.
DONE WHEN
· Test suite is green and behavior is unchanged
· Comment count is down to under ten, with zero commented-out blocks
· Every surviving comment states a why, a warning, or a legal fact
Promote Comments to Names
At ten specific sites, make the code carry the meaning the comment was carrying, then delete the comment. This is naming and extraction doing Chapter 4's job.
- Find ten places where a comment props up unexpressive code: magic numbers with explainers, dense booleans with a note, section labels inside a long function, a cryptic regex with a prose translation.
- Replace each with a named constant, an extracted predicate, an extracted section function, or a well-named validator.
- Delete the comment at every promoted site and run the tests after each one.
- Reread the file top to bottom and check each new name actually covers what the old comment said.
hint
For a regex you usually cannot make the pattern readable, so name the function for its contract and keep one amplification comment inside only if a corner is genuinely surprising.
hint
No bare numeric literal should remain where a comment used to explain it.
DONE WHEN
· All ten comments are gone and a named symbol exists at each site
· No new name uses temp, data, check1 or similar noise
· Tests stay green through every single promotion
The Shape Pass
A pure formatting refactor on a logically fine but visually scrambled file: no logic edits, no renames, just layout until the shape mirrors the structure.
- Take a file with declarations far from use, erratic blank lines, related helpers at opposite ends, and long lines.
- Sweep one: move every local declaration to within a few lines of its first use, instance variables to the top.
- Sweep two: group statements into concept paragraphs with single blank lines between them, never two in a row.
- Sweep three: reorder functions so every caller sits above its callee and conceptual siblings sit adjacent.
- Wrap lines to a fixed width, unify indent width, then zoom the file out and squint at the blocks.
hint
Do the three sweeps separately; mixing them is how a formatting pass accidentally becomes a logic edit.
hint
Verify move-only by checking the diff contains no changed statements, just relocations and whitespace.
DONE WHEN
· Tests green and the diff shows only moves and whitespace
· Every local is declared within three lines of first use and no two blank lines are adjacent
· Squinting at the zoomed-out file shows blocks that match the logic
The Team Rule
Play tech lead: write down a six-key style contract, then bring every file into compliance with your own rules. Which rules you pick matters less than that one set governs everything.
- Write a small style contract file with six keys: indent width, max line length, brace policy, blank-line policy, declaration placement, import ordering.
- Hand-roll a tiny checker that reads the contract and reports violations over your source directory.
- Bring every file, including ones formatted to different personal tastes, into compliance until the checker is silent.
- Reformat one file deliberately against your rules and confirm the checker catches it.
hint
This is what Prettier and Black settle for real teams; hand-rolling it once shows you what those tools are actually deciding.
hint
Vacuous rules that everything satisfies are the failure mode — the deliberate-violation test is how you catch that.
DONE WHEN
· Six rules are written down and the checker reports zero violations
· A deliberately misformatted file is flagged by your own checker
· Tests remain green throughout
Go deeper (after the bench)
Read Clean Code Chapters 4 and 5 now that the work is behind you: Chapter 4's before-and-after prime generator listings are exercise two in miniature, and Chapter 5's newspaper metaphor is exercise three's spec. For one free companion piece, read Jeff Atwood's "Code Tells You How, Comments Tell You Why" on Coding Horror — the triage rule compressed into a sentence, with fair pushback on comment zealotry.