Add Tone Indicators to Your Pull Requests

It is a truth (almost) universally acknowledged that a single software developer in pursuit of good coding standards must be in want of peer review. Pride and Prejudice jokes aside, good codebases are rarely built by individuals. Peer review and testing processes are important for catching bugs, identifying risks, and, above all else, enforcing code standards. Effective teams provide balance and promote best practices through peer review and analysis of each others’ work as parts of a whole.

In an ideal world, such a process is easy. You spend a while crafting the best solution to a problem, submit it for a pull request, someone else hits the big green button, and then you merge and move on to the next thing. More often than not, though, you have not written the perfect, best, solution to the problem.

However, the process of discovering this is neither easy nor smooth. Someone may respond to your work with a comment that completely disagrees with your approach, or ask a question phrased in a way you perceive as aggressive. Pull request review is just another form of interpersonal communication, and like any other form of communication, it’s wrought with potential for offense, distrust, and argument.

Conventional Comments

A coworker on a past project introduced our team to a proposed solution for this exact friction, a resource called Conventional Comments. The concept is simple: annotate your comments with agreed-upon terms — including tone indicators — that denote the nature of the comment, the urgency to address it, and the degree of change necessary to accomplish the task.

For example, if a change is something that is well and truly broken in your opinion, that’s easy to communicate with fix or issue, blocking:

In contrast, say there’s something much smaller you still want addressed, but you acknowledge that it’s not technically broken. You may communicate with terms like nit, polish, or pattern:

And then what do you do when you have a suggestion to make? Or a question? Well, just annotate them as such and be on your merry way:

Another one that we liked using was praise. It can feel good to acknowledge and be acknowledged for doing good work, so take a shot and just do it!

The Power of Annotation

This concept of annotation is not only limited to these terms. There’s denoting something as a blocking vs non-blocking change, specifying what the issue pertains to (UX, code standards, etc.). My team also marked things as todo or chore to indicate a fix that was necessary but small.

The true beauty of adding tone indicators to your pull requests is that you can make these comments as rigid or as loose as you like. But the additional information helps demystify what you are trying to communicate and takes the focus away from interpersonal communication and toward the overall goals of a project and the team’s work. It can also help you frame feedback as something that has a purpose, and not just leaving feedback for the sake of commenting on something. Peer review is important, and the smoother teams can make the PR process, the healthier they will be.