@@ -199,16 +199,20 @@ for the author and everyone on the team to learn.
> *Perfectionism is the enemy of progress.* (Winston Churchill)
Nitpicks are requests for minor changes that address personal preferences or negligible
code improvements.
code improvements. They can create a lot of noise in a code review and at best, bog down a review, or at worst, create a toxic experience for the author.
Nitpicks are born from a wonderful place for most reviewers of wanting to ensure they
provide the most end-to-end review possible and highlight every single potential issue.
But they come at a cost:
When writing feedback, use [conventional comments](https://conventionalcomments.org/) to
clearly communicate intent. In particular, leverage the **blocking** and **non-blocking**
decorators to signal priority:
- They create needless MR cycles (explicitly or implicitly).
- They create cognitive load.
- They can possibly damage the contributor's morale.
-**`blocking`**: The merge request should not be merged until this is addressed.
-**`non-blocking`**: A suggestion or observation the author can choose to skip. It's understood that non-blocking items will not necessarily be addressed unless the MR is primarily for discussion or exploration.
Nitpicks can create a lot of noise in a code review. They can, at best, bog down a review, or at worst, create a toxic experience for the author. Instead please split your feedback into 'blocking' or 'non-blocking' items where it's understood that the 'non-blocking' items will not be addressed by the author unless the MR is primarily for discussion or exploration.
Avoid labeling comments as "nitpick." If a comment isn't worth blocking the merge request,
mark it as **non-blocking** instead. This preserves the feedback while removing the
implicit pressure of an additional review cycle.
If you, as a reviewer, notice that all your feedback is non-blocking,
consider approving (and merging) without requiring an additional review cycle.
To see more reasons on this topic, check out the [stop nitpicking](https://blog.danlew.net/2021/02/23/stop-nitpicking-in-code-reviews/) blog post.
