Semantic Code Reviews

Motivation

A lot of information can be found online about suggested best practices for pull requests (PRs) and code reviews, particularly regarding the ideal size, scope, and description of PRs, as well as the desired response time and comment style for code review comments.

However, in many discussions, the style of comments is not satisfactorily addressed, despite its high significance. Comments have the potential to trigger emotions and make code reviews stressful. General advice is given that comments should be polite, respectful, show empathy, focus on the code rather than criticizing the author, and be crafted carefully.

I think that may work, but I also feel that a lot of time and energy are spent coping with the general disadvantages of written communication, such as the lack of tone and body language. Code can be rather complex, and exchanging opinions about code should ideally be possible without much overhead.

In a nutshell and with a touch of exaggeration, writing code review comments should not feel as time and energy-consuming as composing a business email.

Interestingly, the Google best practices briefly mention the possibility of labeling comments to convey intent. I was intrigued by this idea and elaborated on it by defining labels for various situations. I introduced the concept to my team and it was adopted with great enthusiasm. The next section explains what it is all about.

Semantic comments

With every comment, the reviewer has expectations on how the comment should be treated by the author. In particular, they might expect a brief answer, further discussion, or an immediate change.

The idea of semantic comments is that the reviewer prepends every comment with a label to clearly express their intent and expectations.

The following labels have been proven to be both useful and sufficient. The term change here refers to a change in the source control sense, i.e. addition, deletion and modification of code.

Remark

I have a simple remark, no change or answer is expected from my side.

Question

I have an honest question and I expect an answer.

This label must not be used for rhetorical or leading questions. Instead, use one of the other labels and express yourself without employing rhetorical or leading questions.

Hint

I don't expect any change or answer in this review, but you may find this interesting and consider it for the future.

Suggestion

I have a suggestion and I expect that you think about it. Whether you accept it or not is up to you.

Important

This is important to me and I expect a change. If you strongly disagree I expect that we discuss this further.

Crucial

This code must not be merged. It has a severe issue and must be changed in order to avert harm.

These six easy-to-grasp labels greatly simplify the written communication in code reviews. The unstructured part of the comment can be kept simple and direct because the intent and expectations are encoded in the label.

Note that the choice of the label not only depends on the content of the comment but also on how important it is to the reviewer. For example, consistent naming might be a suggestion for one reviewer but an important point for another reviewer.

After the first comment with a semantic label, there are usually regular responses, i.e., without semantic labels. However, in some situations, a follow-up response with a semantic label might be useful, as demonstrated in the following example:

Conclusion

Communication is hard, in particular written communication. For code reviews, written communication can be greatly simplified by semantic comments. The reviewer's intent and expectations are encoded in labels, allowing the unstructured part of the comments to remain simple and direct.

This approach of semantic code reviews reduces the cognitive pressure of developers, allowing them to focus on what is important: understanding the code and expressing their honest opinion without unnecessary overhead.

Ultimately, semantic code reviews can increase the speed of your PR reviews, result in better code quality and make the developers in your team happier.

Sources

• Google Engineering Practices Documentation