Effective Communication in Code Reviews: The Conventional Comments Approach

Intro

Adrienne Braganza Tacke: Welcome to GOTO Unscripted. We are back. But this time, these seats are switched. I'm Adrienne Braganza, and I'm here now going to interview Paul Slaughter, who interviewed me initially in an old episode. So welcome, Paul.

Paul Slaughter: Thanks. I'm excited to talk again.

Adrienne Braganza Tacke: Yes, I am too. For everybody who may not have heard our first episode, can you introduce yourself briefly and what we like to talk about and probably what we will talk about in this episode.

Paul Slaughter: I am currently a software engineer at GitLab, and have been there for a while. But I've invested a lot of energy in our code review culture and developing some communication ideas that evolved into conventional comments and that has been referenced a bit on how we can improve communication and code review. Through GitLab, I'm involved in a number of other code review oriented things. And I was so excited to meet you because you're deeply involved in code review oriented things.

Conventional Comments: Origins & Structure

Adrienne Braganza Tacke: Just a little bit. So that is actually a great segue. The whole reason I met Paul was, I wrote a book called Looks Good to Me, and conventional comments are something I absolutely needed to include and talk about in the book as one of those good communication patterns. When I was writing that part in my book and in general just talking to teams, there's always this friction when it comes to comments and whether or not they're useful, whether or not they're actionable, and whether or not they take too much time for the reviewer and the author to kind of get on to the same pitch.

In my own experience, not having seen conventional comments or anything like that, my team kind of naturally came up with what we called comment signals to kind of tag our comments and to classify them so that we could quickly understand, hey, you need to do some work on this comment or hey, this comment is purely informational. So I'm super interested in the story behind conventional comments. How did this come about? Is it similar to where you were working with the team and this is how you kind of created it? Or were you just like, we need to fix the problem, and this is what I'm going to do right now? What's the story behind conventional comments?

Paul Slaughter: That's a great question. It was very organic, but also a lot of it oriented around me feeling the problems with some of our code review communication and not accepting just the status quo of "don't ever take code review comments personally, you need to just have thick skin" and you need to try to also kind of predict whatever someone else's intentions are.

When I first joined GitLab, GitLab was a fully remote company. So all of the engineers are working for the most part very asynchronously with each other. Code review is a very critical activity at GitLab and people are located from all around the world. I speak English as my first and only language, and I work with a lot of other people that know a lot of other languages, have a lot of different speaking styles and cultural differences.

I remember sometimes your feelings get hurt in code review, but I remember mainly just feeling frustrated and confused at how I don't understand what someone wants me to do because I would just get a comment like, "hey, it shouldn't be done this way." Period. And I would like to engage more in that.

No part of me felt like I was in any position to follow, and I didn't even know what is a good way to improve our communication. But I started as I gave code reviews, just really thinking about how to make it super clear. And I want to make it really easy for whoever receives comments to understand what I am asking for. And how do I make that where there's none of that room for misinterpretation. Everyone seems to have a very self-critical voice in our heads, and there's none of that room for misinterpretation or fights.

So for me, over-communication is a big deal. And just labeling what your intent is is really important. But then also as I started toying around with this, I've really kind of narrowed in and there's like five-ish labels that all of my comments kind of orbit around. I'm always leaving a suggestion, highlighting an issue or asking a question, and then I'm giving a polish or every once in a while doing a nitpick and very rarely does it orbit around that.

But for me, it's really helpful to give myself a constraint in that way so that we're not also just holding up merge requests from this very vague, open-ended discussion that gets created.

Adrienne Braganza Tacke: I like that, and I think that coming from a place of empathy and wanting to be clear, you mentioned you just want whoever receives your comments to understand you. I think that's something we can all relate with where we just want to be understood. And that's usually a point of friction in any type of communication.

So the fact that you're over communicating, especially in a company of all remote employees like you kind of have to be on the side of over communicating, right? For conventional comments, the typical format for anybody who may not have known it is there's a label. So these are the labels you are talking about. And I'll ask you super quickly what the five are. You mentioned you are trying to sort of gravitate towards a label like nitpick or praise or suggestion and then you can add some what you call decorations and then after that is the subject or typically the comment itself. Now this format is this? has it always been like that or did it kind of evolve to include all of these pieces?

Paul Slaughter: I think it's always been like that because for better or for worse, I mean it in every bit of praise to conventional commits. So it's very much the same format of how we can label our commit messages as this is a feature or fix or this is a chore or docs or whatever. And I found that to be super helpful as you look through your commit history.

The structure was very similar because I felt like that was very natural for me. But also it's a very common structure that we're going to see in any kind of written communication from software engineers where we kind of do this labeling. And there's other preexisting stuff as well, because people for years and years have found ways where you talked about having these comment signals. And some people do these like emoji things.

The challenge for me was I want someone that has no context to see the process of conventional comments to understand the purpose of it too. So it's like I'm trying to over optimize for no context. It needs to be really clear what is the intent and the message of this thing.

Adrienne Braganza Tacke: Totally. And to your point about emojis, even among ourselves, a one emoji could mean something in this generation and it could mean something else in a different generation. So while it might seem obvious to maybe tag comments with emojis, like you said, it may not mean the same thing to everyone else, let alone to the rest of the world.

The Most Common Labels and Their Uses

So for the five that you mentioned that you kind of gravitate towards, if anybody goes to the conventionalcomments.org website where it's a great description of how to use it and some examples of it, you do list a few labels that people can start to use, but there are more than five. So I'm curious to see what are the five that you tend to end up using the most.

Recommended talk: "Looks Good to Me" Constructive Code Reviews • Adrienne Braganza Tacke & Paul Slaughter • GOTO 2024

Paul Slaughter: I think three are like I use 90% of the time. And it's really helpful for me to limit myself to. That's one of the key features of adopting this process when I'm giving feedback. If I am highlighting an issue, asking a question and giving a suggestion all in a paragraph that's unlabeled, it's really difficult for whoever receives that to respond appropriately or understand maybe what your intent is.

So, suggestion, issue and question are the main labels that I use. And then playing around with this is a blocking question that definitely happens. Or this is a non-blocking question or this is a non-blocking issue. It's like, "hey, we're actually kind of introducing a very edge case here, but I can see how this merge request is still profitable, so let's go forward."

Suggestions sometimes - any time I'm suggesting a change, whether it be maintainability or sometimes there's an issue, it's like, "hey, we actually can't do it this way. Here's a strong suggestion. You really kind of have to do it this way." But sometimes if I want to be a little bit more, I'll replace the suggestion with a to-do. If I'm saying, "we just have to do this, this is part of our guidelines."

But usually it either starts with a suggestion, issue or a question. But then every once in a while, I want to be a bit more descriptive than just suggestions which are pretty vague. Issue is like I'm highlighting an issue. Sometimes I'll pair it with a suggestion. And so it's like an issue: "Hey, you actually broke our home page. Here's a screenshot of what it looked like before. This is what would have happened if we merged your merge request." And then I'll add a horizontal line and say suggestion: "Here's a patch that actually fixes what you're trying to do. What do you think of this?" And so I'll pair some of these comments together.

But if you allow me to keep ranting on, I really highly recommend people being more expressive with their labels. I tried to include some expressive ones. For me to-do is one I really like. Polish - people sometimes conflate nitpicks when they're really just wanting "hey, could we just polish this up?" And sometimes that's not necessarily being nit picky.

So if this is the first time I've received the code and there's been no cycles on it, I will definitely say "here's some polishing things we can do." We're not talking about white spacing or stuff that a linter would catch, we're talking about maybe variable naming and that kind of polishing thing.

I brainstormed and thought a lot. At GitLab we don't have synchronous engineering collaboration meetings a lot because of time zone inclusivity. A lot of our communication is asynchronous and code review is our chief engineering collaboration vehicle. So when I'm looking at someone's code, this isn't just an approval process. This is a collaboration process.

Oftentimes through the merge requests it's like I've maybe gained a new perspective on a problem or "have we thought about doing this kind of thing." So I'll leave a brainstorm or thought - I'll use these as labels and they're usually non-blocking. And sometimes they'll evolve in other discussions or sometimes I'm just bringing up that little idea that I had and they're like "oh my gosh, you're right, we totally got to do it this way" and then the whole merge request looks different. And that's a good thing because then we collaborated.

So three main labels: issue, suggestion, question. But I definitely have maybe 5 or 10 that are in the toolbox and I pick and choose when I want to be expressive.

Recommended talk: Small PRs, Big Impact: The Art of Code Reviews • Adrienne Braganza Tacke & Sasa Juric • GOTO 2025

Navigating Disagreements in Code Reviews

Adrienne Braganza Tacke: That's always good to have. Usually if we limit ourselves too much, then we're spending more time trying to work within those constraints than just adding another label or just adding another comment signal. Now, for anybody that may have heard people say merge requests, that's because GitLab uses merge requests (MR). So this is basically similar to pull requests or PRs if you're listening and you're like, what's a merge request?

I'm very curious. I know that you are very lucky to have this all remote environment and you speak about the code review being kind of your chief area where you collaborate. This is where you mostly communicate with your team members and this is where a lot of discussion happens naturally, because of the way your organization works.

But for example, in some of the comments, I know I ran into this issue where sure, we're using conventional comments, and we agreed upon some labels. Sometimes folks will use one label and then they get hung up on the actual label to use. I'll give you an example. Someone writes some feedback and they make it a strong suggestion. But when the reviewer, the author, excuse me receives that and it's clear that the reviewer is making a strong suggestion, but they don't agree with it, they actually think it's not the level of suggestion or something that really needs to work on. It's more of a nitpick.

So this kind of tends to happen even if we have these tools like conventional comments or labeling them to be more clear. Do you have any stories or advice on if you've run into that and how to get past that? It's basically people having a different opinion of what the labels mean.

Paul Slaughter: A couple of things. One, I wouldn't recommend labeling something "strong suggestion." That may come off a little strong, but I also might be a little too polite at times. But I think that's a feature and a good thing.

The labels help me classify my intent and my posture. When it comes to a review, I shouldn't come thinking that I'm going to need to be making all these objectively true statements. I should be coming with a posture of curiosity, and this is my suggestion.

I like it though, when someone now has the discussion because I've labeled it as a suggestion, the discussion can be like, "oh well, I actually think this might just be a little bit of a non-blocking nitpick, what do you think?" And we're talking about now what is the severity of this and how do we feel about it individually and how do we move forward.

As opposed to if I don't label anything and I just say, "do this thing," sometimes this conversation then just devolves into why or why not we should do that thing. And then I will give you my reasons. And we write essays to each other and we collect data and we figure out which thing was the best thing, when in reality we could have just short circuited all of it because this is probably non-blocking. We keep going or let's open up a follow up issue for it.

We're now discussing the nature of the comment as opposed to the comment itself. So in many ways, I don't see that as something to avoid. It's a feature that happens because it's like, "hey, I see that this is a suggestion to you." Or if someone does "suggestion blocking," that's usually how I would see it. I see this as a blocking suggestion to you. I feel like this is non-blocking for these reasons, and that's a more productive conversation.

And hopefully you are operating in a team where we trust, like, okay, I'll follow up on that. And I love when I read your book and you talked about the working agreements, and that really helps establish a culture of trust that really helps accelerate some of the code review discussions.

Recommended talk: Reading Code Effectively: An Overlooked Dev. Skill • Marit van Dijk & Hannes Lowette • GOTO 2025

Code Review Culture and Communication

Adrienne Braganza Tacke: Absolutely. I think that what helps here, too, is that your team or any team where this is a bit more functional comes from a place of objectivity. Again, not taking any feedback as personal or taking it as the person who's reviewing has more meaningful feedback or comments than what I could ever give.

I think a lot of people forget that if you are open to the discussion and there is objective and constructive feedback to talk it out, there's nothing wrong with talking it out. I think if both parties approach it in that way, rather than just assuming they have to take everything that the reviewer says as law, then I think a lot of people will have a better time with code reviews.

Paul Slaughter: I like to add to that. When I'm the author and I'm anticipating my code being reviewed, I try to frame everything - and you write about this really well - but I try to frame everything where I want the reviewer to want to approve and accept it. I want them to feel really good about it. And a lot of that comes from I want them to feel a sense of ownership with it. And a lot of that means they will have comments and suggestions on it, and sometimes they're going to choose to name something I wouldn't do.

But when I'm submitting code, I realize this isn't ours, and it's going to be a lot better when we can all co-own it. And so a lot of times this sounds weird but I will leave things in the code knowing that this reviewer is going to want to change it. That's okay with me, and I'll let them ask for it and then I'll change it. Now we have a sense of ownership of it.

There was a story that I remember hearing back in the old days of programming computer science. They had some software team dealing with a difficult customer. They were building some sort of chess simulator or whatever. The customer, no matter what, was always asking for things to change. And one of the engineers picked up on this, and they were right up to the deadline and anticipated - they added this weird flying duck around the Queen's head or something, knowing that in the meeting, the person was going to find something to change. And so they were just going to sneak something in there so that the person would be like, "oh, can we get rid of that duck?" And they were like, "sure, we can do that." And then "okay, we're good, we got past that customer meeting."

That happens in code reviews. When you submit something, people are going to want to contribute and change things, not necessarily out of malice or a bad thing. That's a really good thing. So not taking things personally when change requests come.

However, this is the question I want to ask you. How do you feel about the statement of "Oh, you know, this is just about the code. It's not about you. Don't take these things personally." Have you seen this play out in your experience? Do you feel like there's some wisdom in there, but there's some danger zones in there as well?

Adrienne Braganza Tacke: I think the intent behind those pieces of advice or guidelines, like "focus on the code, not the developer" or "don't take things personally, it's just about the code" - it can go both ways if the team is not on the same page about what that means. That's why I tend to qualify that with something like a team working agreement, where if you're all on the same page about what different things mean, then you're more likely to not have misinterpretations of that.

I have seen this been misinterpreted the wrong way, which is to focus on the code, not the developer. So someone will maybe make a suggestion on a code review, and it's a really harsh suggestion, or the way that it was written was very aggressive, very abrasive. And it may still focus on the code - they may not be calling out the author directly or saying that they did it in a stupid way, but they're kind of hiding behind that guideline to be a jerk. That's very manipulative.

I've seen that on teams where another example is maybe someone using their seniority or using their status on the team. Maybe they've been there the longest, or they have the most experience in something. And so whatever they say goes and again, they use that as an excuse like, "well, I'm focusing on the code and I'm only doing this to make the code base better. I'm trying to make it great."

But what they're really doing underneath is "this is the way I want the code base to be and everyone else to fall in line." And in that sense, if people are doing that behind the pretense of being objective, but really they're not, that's one thing to watch out for and to call out when that happens. Because yes, they may not be so direct and attack you or anything like that, but that's still a very big problem - hiding behind the pretense of wanting to make the code better.

Paul Slaughter: I've heard that sentiment and there's wisdom in as the individual when you're receiving things like, "okay, I'm not my code. Don't take these things personally." And so even if someone comes with that really strong handed comment, in some sense that's good. But I have seen it used the way you're talking about.

I think that there can be a tendency for people to set up a false dichotomy in their heads of "well, we can't be overly polite or we won't get anything done." The answer is in the blessed middle road of we got to take care of each other.

But I think this thing happens where if you treat it that people's feelings are going to be connected to their work because they're going to care. You want your team to really care. If your team cares about what they do, there's nothing you're not going to be able to do. You want a team that cares and puts themselves into it. And that's a very rewarding experience too. It's a very rewarding job to be involved in. I want to care about what I'm doing.

But because of that, when I communicate, if I'm communicating in terms of "hey, your work product was okay, but it wasn't good enough, here's the thing to make it better" and you do that ad nauseum, they're going to feel like "this sucks, I'm never acknowledged for anything good that I do" or they'll have that comment of "I can't do that, I'm not good enough" - they'll totally internalize that perspective as well.

I think the posture we bring to code reviews is so critical, and it's collaborative - together working on a common problem. And that's why labels for me are really important. Because sometimes when we want to just polish things up, it's a different posture of communication to say "hey, this is really good, here's this quick patch that polishes some things up" as opposed to "before I approve this, you need to check all these other things you missed." That is not a very enjoyable engagement.

I highly recommend anybody listening to just really reflect on themselves. What's the posture you're bringing to code review? And the conventional comments are just a helpful reminder. They're not going to force a posture because you could totally misuse it in a bad way. But it's a gentle reminder of "hey, we're to be asking or to be creating suggestions. We should be collaborating together in these ways that are constructive, not destructive." And what would be a destructive label? I don't know, I'm not going to try to create one.

Code Review Weekly Workshops and Team Learning

Adrienne Braganza Tacke: I don't see many - I guess your mileage may vary with your team. Some teams might be completely okay with this, and as long as you're all on the same page of what those mean. But I don't know if that would be hilarious to use.

But no, I totally agree. How you approach code review as a team is always going to determine how well that process goes for your team. Switching gears a bit, since you are so entrenched and dedicated to the code review process at GitLab, I've also seen that you've started this code review weekly workshops. Based on my last look, there's about 39 episodes, and it started in 2022. Can you tell everyone what it is? It seems like a really cool thing. It almost looks like a retrospective with your team about what you could improve or what is not going right or what did go right in a previous code review.

Paul Slaughter: To frame it, I would suggest any organization to pick up a similar practice. I'm not promoting "check out our code review weekly workshops." Feel free to do that. But GitLab is a weird company where we record all of our meetings and we post them publicly. So if you want to see how we do things, it's all very transparent.

The Code Review Weekly Workshop grew because we received a lot of - there was a growing problem for years and years of you getting a different experience based on who's reviewing your code. That's something I think many organizations would empathize with.

At the same time, we had some organizational issues where our maintainer set was being overloaded, and we really needed to grow the amount of maintainers. But that's a risky thing with a development process like GitLab, because the role that those maintainers hold is critical to the quality and maintainability of the code base, but also the end user quality.

GitLab is a large, monolithic software that like any kind of project, you just have these peculiarities that grow with the project. As you have experience with the project, you kind of learn "oh, wait, we got to be careful about this context" that very few people will realize. And it's also open source, so we can't always afford to trust the author, for lack of a better word.

So we just needed to have a place where we were discussing what was happening in code review with other people. Like "hey, I had this weird code review and this is how I approached it, this is what the thread looked like." Or, "hey, I had this thing, totally missed this thing, it caused an incident - we've got to make sure we watch out for these things when we do code review."

It's just this very open forum for the GitLab team members that are engaged in code review or curious about it, or learning how they can be more efficient. Or little hacks that they've developed themselves just to share that with their team, so that we can try to normalize the code review experience as community contributors or other people submit merge requests.

Because we have a large number of engineers and we do something really well, which is we don't have a lot of just intergroup code reviews. We try to have all the engineers reviewing each other's stuff, and that's really good because it helps break silos. But it's also challenging because sometimes you don't have all the context.

So the Code Review Weekly workshop developed because we realized we're going to have a lot more maintainers soon, we have a lot more people developing code, we've had this problem where code review was an inconsistent experience. I think it's going to look different for different teams, but I think it's really good to keep talking about how code reviews happen and just keep that conversation going. And in the background as people engage in those discussions, you'll see the code review experience start to normalize to a consistent experience.

Adrienne Braganza Tacke: I like the intent behind that, especially because you have so many more reviewers in your pool. So I can empathize with getting a different experience every time depending on who my reviewer is. And I'm very curious. So let's say someone does bring something up, like "I had a weird experience" or "my review is not quite the same." Does this mean that the person who had that experience and the reviewer who may have given that experience - is this almost like couples therapy? Do they go to this workshop and work out what they did? Or is it just the person who went through this type of odd review talk about it with other folks?

Paul Slaughter: That's a great question. I haven't facilitated a review of couples therapy yet. So it's usually one person sharing either they've received something that was really good and that's a great thing to share, or they receive something that was challenging. And that's a great thing to share in a way that's non-blaming, because you are doing it publicly. So we're sharing it from this place out of curiosity of what happened here.

And that takes a little bit of work to process how I feel about it. But the result is really positive, where we take all of these experiences as learning experiences.

I'd be really curious, and I think you say this in your book and it's really good, and it's something that we don't do at GitLab a lot because of our organization. But you bring up "let's short circuit, let's have a sync call to flesh something out." And I think sometimes when you've had these async essays going back and forth, it takes just five minutes - you just have to look at each other and acknowledge each other's humanity, and that we both probably have the right goals in mind. And then we can move forward.

It's not necessarily couples therapy. I love the idea, though.

Adrienne Braganza Tacke: I just wonder, because I'm thinking about this concept and wondering if that would have helped some of my earlier experiences where I had a really bad review. I guess from my perspective, I was the one who received the challenging review, I would want the reviewer in some form to either change or to at least understand why it was such a challenging review.

I see that you post them publicly, and I would be like if I was on the other side, if I was a reviewer, I'd be like, "oh gosh, I would watch these every week and hope they're not talking about me," you know? Or you could be the other kind of reviewer where you're like, "I don't care, that was me."

Paul Slaughter: It's a great question. And I think it is worth being extra thoughtful. In my early years at GitLab, another collaboration vehicle I tried to promote was pair programming, having regular pair programming times. And it was brought up, "what about doing pairing up on a code review?" and that always felt weird to me because I felt like I don't want someone to feel like they're ganged up on.

But in hindsight, we've totally done this in the Code Review Weekly workshop. And it was really good. I think there's something about knowing that this is going to be public - the intent here is for it to be a learning experience and we're always assuming good intent about everybody involved.

So even if someone did receive a very difficult review, the conversation will be heavily seasoned with assuming good intent on the reviewer, identifying "oh yeah, maybe they could have done this. Whenever this has happened to me, these are some things that I did, if you feel like it was like this, here's the process for doing it."

But there's definitely some episodes that we didn't post the recording of because we want to be cautious. It's funny - code review elicits some feelings, and I don't think the answer is to suggest "well, you shouldn't feel anything about it." I think that's a good thing. But we should be curious about why these feelings are elicited when we engage in code review, and try to solve them.

Adrienne Braganza Tacke: That's a great way to put an end to this particular episode. The time flies by so fast, but yeah, Paul, we could talk about this forever. I'm considering starting a code review podcast.

Paul Slaughter: There you go.

Adrienne Braganza Tacke: There's so much more to talk about.

Paul Slaughter: If we can, I'd like to sneak in one quick thing, because I feel obliged. I've engaged in a lot of engineering discussions, and there's a lot of engineers that don't like using things like conventional comments, and don't like being overly plain in communication. I totally get it - they want to maximize efficiency in their communication.

I personally have had to hone in on efficiency with code review. And I have developed a number of efficiency tactics that help me. I do a lot of code reviews at GitLab. And I also try to make sure I'm maintaining politeness. So don't ever think that being polite means you can't be efficient.

But some of the main things - and we talked about this offline, and I asked if you could please put this in your book - is using patches. The more code that's in your comments is better, the less English language someone has to parse. I'm always reviewing code locally and generating patches and sending that. That's 95% of my code reviews, using patches. It helps save so much time.

Rather than shotgunning 20 Polish comments I have just one Polish comment: "Here's the patch. Feel free to take or leave whatever you want to," and that kind of thing makes a huge difference.

Then the other thing that I do is I set a timer for myself when it comes to code review. Because after a certain amount of time has elapsed, I know I'm not going to be leaving suggestions and patches as much as I'm going to be asking questions now. That's a whole other thing we could elaborate on sometime, but I feel like it pairs well with polite conversation, because one of the feedbacks is always "I don't have time to be polite" and you really do.

Adrienne Braganza Tacke: There's always room for empathy and being considerate. I agree. Well, thank you so much, Paul.

Paul Slaughter: Thank you Adrienne.

Adrienne Braganza Tacke: Thank you, everybody, for listening to this other episode of GOTO Unscripted. And who knows, maybe we'll be back for more. There's certainly a whole list of things we could continue talking about. But until next time. Thanks, everybody.