The Lettergrade Rule

How do you know when a code review is “done”?

Let’s say you are the reviewer and see many small changes you’d like the author to make. At some point, you’ll agree that the introduced behavior changes are correct or at least harmless. The remaining comments are largely stylistic or involve misalignments in minor architectural choices.

The letter grade rule is a lens for determining if any remaining comments justify blocking the change. It goes something like this:

Does addressing your comment or doing what you suggest improve the reviewed code by at least half a letter grade?

Your comments are not worth blocking the review if the answer is no. Instead, leave them as suggestions that the author can take and do with it what they will. Then, move on with your life.

This route is respectful of the author’s time and yours. It also implicitly places some amount of trust and responsibility on the author, which is empowering.

You might now wonder what constitutes a half-a-letter-grade improvement.

Here’s a non-exhaustive list of things it is not:

• Stylistic choices that don’t violate the project’s style guide. Please choose a coding style and enforce it via a code formatting tool if this is a common cause of disagreement. Use a code formatting tool even if it isn’t a common cause of dispute. There should be no reason to format text with a spacebar in 2022.
• Choice of identifier name; unless the name diverges from the project’s domain model and naming convention or objectively hurts readability.
• “This isn’t how I would have done it.”
• There are minor grammar issues or word choices in comments that don’t decrease the readability of the code. You should be able to trust the author to make those fixes and submit the change without you having to do another pass.