6 Composing effective code review comments
This chapter covers
- Why code review comments are so important
- What makes a comment effective
- How to write effective comments
- The 5P process for determining whether suggestions are valid to add
- The MMG Exchange for finding a solution that is clear to devs with opposing “objective” viewpoints
- Comment signals, MoSCoW categories, Conventional Comments
- The Triple-R pattern for requesting changes or additional work
Have you ever been in a social setting where multiple people are conversing? Genuinely interested and engaged individuals are sharing their thoughts on a subject—some even ask questions to better understand the person they are talking to. Some people interject, try to impress, rarely listen, and try to place the spotlight back on themselves (sometimes, we might even get into a debate with these folks!). One or two don’t employ emotional or social intelligence, usually replying with a snarky, harsh, or inappropriate tone. And there are those who don’t say much, if at all.
These individuals are just like the types of comments we may receive (or give!) on a code review. Comments can be thoughtful and relevant or propose unsolicited, “better” implementations with no reasoning to support why. They can be rude, condescending, or mean and add little to no value to the review (life is just a bunch of patterns, huh?). Much of the dread we feel comes from anticipating comments that could start a conflict.