Structured comments that can simplify and speed up PR reviews in teams

Comments on pull requests are, in some teams, a topic of heated debate. Depending on the team, they can become blurry or start fiery discussions due to missing human ques in situations where people don’t or can’t talk to one another. This can be due to setup or difference in time-zones.

There seems to be a solution through an initiative called “Conventional Comments”. The idea is to quickly indicate the intention of one’s comment using a specified structure:

<label> [decorations]: <subject>

[discussion]

The legend is as follows:

label - signifies what kind of comment is being left (only one label).

subject - the main message of the comment.

decorations (optional) - extra decorating labels for the comment. They are surrounded by parentheses and comma-separated.

discussion (optional) - supporting statements, context, reasoning, and anything else to help communicate the “why” and “next steps” for resolving the comment.

You can see the suggested labels on the initiative’s page. A friend of mine, Jacob Rybacki, who is a QA Architect living in Switzerland, experimented with this approach in his team and agreed to share the initial findings:

1. We often treat the PR comment by default as an issue that people interpret as a blocker. If it’s clear what its nature is from the beginning, it’s easier to see the main problems for a PR and focus on them first.

2. It’s best to start with three essential labels and expand if necessary.

3. Comment templates supported the adoption of the idea on GitHub - it was much easier for people to use the same format.

4. After writing a supposedly blocking comment, the reviewers sometimes reflected that it was their personal opinion and opted to change the label to one that suits better.

5. The convention of the ‘suggestion’ label requires clarifying why the change is and what value it will bring. I personally also add an example where applicable.

6. Adopting might be challenging initially, as people see it as an administrative task. It’s crucial that adding a comment is quick, and templates help a lot here, reducing friction.

7. You don’t need to restrict yourself to a single comment per line - people asked a question and suggestion in the same place.

—

🎈Share this post if you think it can help teams make better use of PR reviews.