4 Practices to Apply When Reviewing Code

soft-skills code-reviews

Over the years, I’ve experimented with various ideas to make code reviewing more rewarding. Code reviewing is not only the place to spread knowledge but also a place to build the relationship with the code author.

Here are 4 practices to apply when reviewing code.

1. Conventional comments

Conventional comments make us appear predictable in code reviews and can prevent us from sounding like a stuck-up person.

  • The intention of our comment is clear
  • The separation between the topic of the comment and the example and / or reasoning of the comment is clear
  • The author knows what they should prioritise on because our comments are well-labelled

I suggest checking out this guide by Paul Slaughter on how to start writing conventional comments: https://conventionalcomments.org/

2. Mind the nitpicking

Feeling strongly about something the author wrote? Ask ourselves:

  • Is it merely our preference?
    • Our preference shouldn’t block the merge request from being merged
  • Is it a best practice that can be configured through the linter?
  • Is it a best practice that can’t be configured through the linter?
    • Think we should practice something? Draft a proposal and share with the team
  • Is it something that can be renamed due to misleading meaning?

3. Masking suggestions as questions

When we mask our suggestions as questions, they can be thought-provoking to the author and the tone of our suggestion is highly likely to come across as friendly. Here are a few examples:

  • Example A
    • Instruction format
      • Rename invitationAccepted to hasUserAcceptedInvitation
    • Question format
      • What if we rename this boolean variable from invitationAccepted to hasUserAcceptedInvitation? hasUserAcceptedInvitation is more clearer than invitationAccepted
  • Example B
    • Instruction format
      • There’s no deprecation comment for fetchAllRecipes. Write it
    • Question format
      • Since we’re replacing fetchAllRecipes function with fetchRecipes function, have we thought about leaving a comment to explain why we must not use fetchAllRecipes anymore?

4. Not shying away from asking

I encourage everyone of all levels to ask questions when struggling to understand the changes being reviewed even if the question sounds foolish. Asking questions is one part of how we improve ourselves.