During my career in software development, proper communication (or lack of it) has been crucial in instigating some creative discussions and/or flame wars during reviews. Tensions were high sometimes, and egos were injured because of a person insisting on the single/double quotes or whatever they suggested/disagreed with.
Two hundred or even more comments later, nothing was accomplished except for some long lasting animosities between team members.
You can agree with me that we need a way to keep the code reviews from falling into the death spiral of constant change requests and toxicity. It wouldn't hurt to make it clearer what the reviewers are actually saying to get their message across much easier, without any added noise.
Luckily I worked with a person that asked many (not so stupid) questions and insisted on having processes for everything and anything. Albeit that's quite annoying upfront, having systems and processes allows you to automate and/or delegate them. It also gives you an operations manual of sorts. This article is based on one trick that I learned from him while I was at intuo.io and I'm trying to note it down now so it's not lost.
To improve communication clarity, the engineering team agrees on a certain number of prefixes that we add when reviewing someone else’s code:
- C:(change) - We absolutely have to change this, whatever this is. It’s related to something that breaks existing functionality, or could introduce bugs/performance issues in the future. So something that needs to be addressed before the PR is approved
- Q:(question) - This is a general question to try to understand the issue at hand, no code changes are usually necessary for these types of comments
- NTH:(nice to have) - I would like to have this implemented alongside the thing we are already implementing, this can be whatever you heart desires, but don’t expect it to be done, unless it actually adds to the quality of the feature
- PP:(personal preference) - This comment is something akin to (I would personally implement this solution like this…, but your approach still works well). We can take this one as a teaching(learning?) experience where you might suggest a better (for you) solution for some problem
Thanks to Maarten Mortier for inspiring this approach and a lot of other procedures/systems I have built into the products I work on.
Top comments (0)