A review can be a correction or a lesson. The same feedback, written differently,
is either one or the other.
The correction
“The function is too long. Split it into two functions.”
This is correct. It is also lazy. The author learns nothing except that the
reviewer does not like long functions.
The lesson
“This function does three things: parse, validate, and persist. Each of these
is a decision point. When the parsing fails, someone reading this wants to know
whether the validation failed or the persistence failed. Right now they cannot
tell. Split it into three functions so the failure point is clear.”
This teaches why. The author learns that the reason to split is not fashion,
it is clarity. The next time they write a function that does multiple things,
they will make the decision themselves.
The comment that changes code
“What happens if user.name is nil?” turns into a check, a test, a fallback,
and the code is more resilient.
“This will crash if the user has no name” teaches why it is a problem.
What reviewers often do wrong
- Correct the code without explaining the reasoning
- Suggest a fix without explaining the trade-offs
- Approve code that works but will be hard to maintain
- Disapprove code that is a little different from how they would have written it
What reviewers should do
- Explain the reasoning: “This pattern makes it easier to test because…”
- Explain the trade-off: “This is slower but it is clearer…”
- Ask the question: “What happens if this fails?”
- Differentiate: “I would have written it this way, but your way is fine too.”
The review I am most proud of
A function was correct but confusing. I wrote: “I do not understand what this
function does from reading the name or the code. Can you rename the function
and add a comment about the three cases you are handling?”
The author rewrote it in twenty minutes and asked: “Is this better?” It was. And
they learned that clarity matters more than correctness.
Why this matters
A junior developer reading a correction learns that they made a mistake. A junior
developer reading a lesson learns how to make better decisions.
The review that teaches is the one that stays with someone for years. The
review that corrects is forgotten by tomorrow.