Explain the why in code reviews

2019-08-25 1 min read

    This may be obvious to most people but it’s still worth reiterating: if you’re leaving a comment on a code review make sure to explain your reasoning. Code reviews are a key component in writing high quality code, improving everyone’s skills and knowledge, and encouraging a strong and collaborative team.

    Code reviews can be a bit clinical with feedback being blunt and a few words and it’s important to add context to all but the simplest of feedback. Experiences and backgrounds vary across the team and what’s obvious to one person may not be obvious to others. Similarly, it softens the feedback and encourages both sides to have a conversation. The act of describing the why also forces the reviewer to slow down and actually think about their reason for the change request. This may, in fact, reveal that the change request is not actually useful or may not actually have a good reason.

    It’s an easy habit to develop and makes one a stronger contributor to the team. It will improve the way the feedback is received as well as encourage the reviewer to adopt a “tabula rasa” mindset and improve their code and thinking as well.