Case Study 1 — The Review Comment That Almost Cost a Contributor

This case study walks through the chapter's anchor move—rewriting a harsh code-review comment into one that is specific, kind, and aimed at the code—using a real-feeling scenario on Raj Patel's chronoparse project. Read it as a worked example of the diagnosis-then-fix pattern: see the comment, watch what it does to its reader, name exactly what's wrong, and rebuild it. The contributor and the exchange are fictional but realistic; the pattern is one you'll find in thousands of real pull requests.

The setup

chronoparse now has outside contributors, which is the success Raj wanted and also a new responsibility: every pull request he reviews is read by a human who spent their own evening writing it. One Tuesday, a newer contributor—call her Mei, three PRs into the project—opens a change that adds support for parsing ordinal dates ("the 3rd of March"). The code works, the tests pass, but in one spot she parses the input string, then parses a substring of it again to extract the ordinal, instead of carrying the already-parsed tokens forward. It's a real inefficiency, and on an ambiguous input the two parses could in principle disagree. It's worth raising.

Raj is tired. He's reviewing at the end of a long day, and he fires off:

❌ The comment Raj almost left: "This is wrong. Why are you parsing the string twice?? This whole approach doesn't make sense. Did you even look at how the rest of the grammar module works? You should know better than to re-parse like this. Please redo it the right way."

He has his finger on "submit." Then he imagines Mei reading it.

What the comment actually does

Read it as Mei will, at the end of her long day, having contributed her work for free. The comment lands as an attack, and it makes four distinct mistakes—each one a thing this chapter named:

And here is the quietest damage: there is a real, useful technical point buried in here—the double-parse is a genuine issue—but it's drowned in hostility. Even if Mei grits her teeth and fixes it, she's learned one thing for certain: submitting to this project is dangerous. The likeliest outcome isn't a better PR. It's that Mei's fourth PR never comes. Raj would have traded a contributor for the momentary satisfaction of venting—the worst trade in open source, where contributors are the scarcest resource there is.

The diagnosis is the chapter's threshold concept made concrete: Raj wrote a comment aimed at Mei, when the problem lives in the code. The code parses twice. That's a fact about some lines of text, not a fact about Mei. Once Raj sees that, the rewrite almost writes itself.

The rewrite

Raj deletes the draft and writes what he actually means—about the code, specifically, with a way forward:

✅ The comment Raj sends instead: "I think this parses the input twice—once on line 12 to validate it, then again on line 18 to pull out the ordinal. If I'm reading it right, we could reuse the tokens from the first parse instead of re-parsing the substring, which would be a bit faster and would also avoid the edge case where the two parses could disagree on an ambiguous string like 'the 1st 2nd'. The grammar module does something similar in relative.py:40 if that's a useful pattern. Was the re-parse intentional, or just an artifact of getting the ordinal logic working? Happy to be wrong here—and thanks for tackling ordinals, this is a feature people have asked for."

Look at what changed, point for point:

1. Specific. It names the exact lines (12 and 18) and the exact behavior (parse, then re-parse the substring). Mei knows precisely what to look at—specificity is kindness, because it spares her the guessing the vague version forced on her.
2. Aimed at the code. "This parses the input twice," not "you don't understand parsing." The subject of every sentence is the code's behavior, which doesn't care who wrote it.
3. A path forward. "Reuse the tokens from the first parse," plus a concrete example to copy (relative.py:40). The comment is a route, not a wall.
4. A genuine question. "Was the re-parse intentional?" leaves room for Mei to know something Raj doesn't—maybe the re-parse guards a case he can't see from the diff. "Happy to be wrong here" signals he holds the objection loosely. This is a conversation between peers.
5. A line of praise. "Thanks for tackling ordinals"—one sentence that tells Mei what to do more of and makes the whole comment land as collaboration rather than judgment.

The technical content is identical to the harsh version. The double-parse is still flagged; the inefficiency and the ambiguity risk are still named. Nothing was softened into mush—Raj still says the true, hard thing about the code. What changed is everything about how Mei will receive it and act on it. She'll fix the double-parse, learn the token-reuse pattern, and—this is the part that matters most—open a fifth PR.

What this case teaches

• Candor and kindness are not a trade-off; vagueness and cruelty are the trade-off. The harsh comment was both meaner and less useful—it was vague and hostile. The good comment was both kinder and more useful—specific, with a path. You don't choose between being clear and being kind; aiming at the code gets you both at once.
• The same technical point can build a contributor or burn one. The bug was real either way. What determined the outcome was where Raj aimed his words. Aimed at Mei, the comment cost a contributor; aimed at the code, it taught one.
• "Happy to be wrong here" is not weakness—it's accuracy. Raj genuinely might be missing something the diff doesn't show. A real question keeps review a two-way act of making the code better, which is what it's for. The reviewer who's never wrong isn't reviewing; they're issuing verdicts.

The deeper lesson is the chapter's threshold: you are critiquing the code, not the coder. Cross that line and your comments change automatically, because you stop writing about a person you're guessing at and start writing about behavior you can see. The same move will reappear at the other end of the chapter, in the blameless postmortem—debug the system, not the human—because it's one idea: separate the work from the person, and the writing starts producing improvement instead of fear.

Try it yourself: Find a code-review comment you've left (or received) that stung. Run the diagnosis table on it—was it vague? aimed at the person? a weaponized question? pathless? Then rewrite it: name the exact line and behavior, aim it at the code, add a path forward, and—if there's anything good in the change—one line of praise. Notice that the rewrite is usually more useful, not just nicer. That's the tell that you were aiming at the wrong target.

Back to: Chapter 34 · Case Study 2 · Key Takeaways