Semantic Code Reviews

Simple and direct comments without drama



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.


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

Remark: That's a nice solution!


I have an honest question and I expect an answer.

Question: Where does this formula come from?

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.


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

Hint: There exists a library for generating fluent APIs: M31.FluentApi.


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

Suggestion: Use a foreach loop instead of a for loop, as it is more concise.


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

Important: Set the initial list capacity in order to reduce the number of allocations.


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

Crucial: Secrets must not be checked in.

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:

ALICE Question: Where does this formula come from?

BOB This is simply the quadratic formula for calculating the x-coordinate of the intersection of the sweep line parabolas.

ALICE Suggestion: Refactor this code and extract a method SolveQuadraticEquation(double a, double b, double c).

BOB Agreed.


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.


Join the discussion on Hacker News.

Thank you for reading. If you have any questions, thoughts, or feedback you'd like to share, please feel free to connect with me via mail. For more updates on upcoming blog posts and library releases, you may follow me on Twitter.

Happy Coding!
- Kevin