This is part of a series on reducing PR code review time, which is important because long feedback loops are one of the drivers of low developer productivity. Here are the other articles of the series with a TL;DR to remind you of the key takeaway, but there are details in the article of how to do it.
- If code reviews take too long, do this first (TL;DR: gather data)
- What to do about nitpick comments in PRs (TL;DR: eliminate them)
- What to do about excessive (good) PR comments (TL;DR: make better PRs)
- Not all PR nitpick comments are bad (TL;DR sometimes you need or want them)
If you are still getting nitpick comments after you have done what you can to eliminate them, try adding a checklist for comments. Here’s an example checklist to start from:
- Is it a bug?
- Does the code violate the specification?
- Does the code violate our design system?
- Is the code reimplementing something where it should reuse our library code?
- Does the code not meet our style guide?
- Does the code not meet our testing code coverage requirement?
- Is the code not consistent with the vast majority of our codebase (especially recently approved code)?
- Does the suggestion have an obvious, objective way to resolve it?
If a suggestion doesn’t meet your criteria for a good comment, then try one of these techniques to improve the comment
- Reframe nitpick suggestions as an (objective) defect with a clear way to resolve it. So, for example, if you “don’t like” a variable name, give a reason why you don’t like it. Some examples that are actually defects: (a) the variable is two letters and you have a standard that requires four or more (b) the variable doesn’t match your naming convention (for example, you always use the word “count” instead of “length”) (c) you don’t understand the variable name — suggest better names — express how the name is confusing you, which is more objective than “not liking a name”.
- Reframe the suggestion as the beginning of a process to update coding standards. When new non-defect, but possibly good comments are warranted, they should start as suggestions that might change the coding standard. In this case, you are going to move the discussion to what ever process you use to change standards (e.g. a retro)
- Make the comment if we are in a situation that warrants it anyway: See Not all PR nitpick comments are bad
If the suggestion is still nitpick that you can’t improve, and it isn’t warranted anyway, don’t make it.