Christian Gill

Code Reviews Comments Convention

A convention to clarify the intention of a comment in a Pull Request (PR) review using prefixes.

xkcd standars

Mandatory xkcd

Although it is possible to express the intent in the way the comment is written, it is easier to do so with a simple prefix. Not only it requires less words but it is also easier to take a quick look at the comments and understand what is the intention/meaning of each one.

My rule of thumb is, only reviews that include [req] and/or [q] should Reject the PR. In other cases just make the review a Comment or Approve.

Prefixes

[req] (requested change)

Reviewer believes something should be changed.

[nth] (nice to have)

Reviewer suggests something better/more thorough/common pattern etc.

[pp] (personal preference of the reviewer)

This shows own opinion on style/unification etc. Might influence the author to apply some changes, but does not provide any benefits (it's not for optimization/better interfaces etc.)

[q] (question)

Reviewer would like to get some explanation on topic.

[fixed]

Author fixed/changed based on the comment.

[wont-fix]

Author declines the request. It should be first discussed with reviewer and explained in comment.

Credits

To whoever came up with this convention 😅

If you know let me know, so I can credit & thank them! 🙏


Happy and safe coding ✌️