Ep. 33 | Looks Good to Me With Adrienne Braganza  ## Metadata - Author: [[Overcommitted]] - Full Title: Ep. 33 | Looks Good to Me With Adrienne Braganza - Category: #podcasts - URL: https://share.snipd.com/episode/5d9f6050-8830-4a7e-baac-01ec3eda7c0d ## Document Notes ## Highlights - **Communication Is The Core Problem** - Misunderstandings and poor communication cause most code review frustrations. - Adrienne Braganza Tacke argues fixing communication beats optimizing tools for better reviews. Transcript: Adrienne Braganza Tacke The research that I've done, both from looking up papers that have been done on code reviews and my own teams and all the common patterns and themes of what was frustrating developers, It always came down to misunderstandings and bad communication. That's really the heart of most of the frustrations we deal with in code reviews. So I think it's super important to take some time to not just think, what tool am I using, or how do I make it faster, or how do I just get the check mark? It's why are we doing this? What are we using it for? What do we all agree is something important to call out or not? And when you mentioned earlier is absolutely true. The first team you work on and the first exposure you have to a code review process, if at all, that's kind of what you carry with you throughout the rest of your career. So if you're lucky enough to have a team that has an established process and has good communication and not just that, but good interpersonal skills and clear people with, you know, A co-collaborative nature of how they want things to be done, then like you're really lucky. Hopefully you learn from that. You see this is what a code review process should be. And I see the benefits of it. And you take that with you throughout the rest of your career. But unfortunately, most folks don't have that. I did. I had a terrible code review process my very first time was, you know, I'm a lot of people relate. I don't say everyone has this experience. But when you just come out on your first like real job as a software developer, even as an intern, you hear about this process. And you're so worried about it, because you're like, I don't want to be critiqued. I don't want to look stupid. I don't want to, you know, prove that I'm not supposed to be in this job. And then you have an experience where you do get your code critiqued and it is very harsh and it is very mean. That could definitely set you up the wrong path. Like you could say, I don't want to do this anymore. I don't like this. Or, you know, some people might be thicker skinned and they're like, yeah, I did write crappy code or whatever. But regardless of all that, I absolutely believe that there's a proper way to do code reviews and that proper way all comes down to communication. So I come back to that every single time. Almost all forms of frustrations and problems people have come to me about code reviews. It boils down to some form of miscommunication. ([Time 0:04:20](https://share.snipd.com/snip/be07d1ba-d40b-4af9-bf42-f3c0a11ed4a0)) - **Formative Bad Review Experience** - Adrienne recounts a harsh early review experience that made her fear code critique. - That negative start motivated her to advocate for kinder, communication-focused reviews. Transcript: Adrienne Braganza Tacke So if you're lucky enough to have a team that has an established process and has good communication and not just that, but good interpersonal skills and clear people with, you know, A co-collaborative nature of how they want things to be done, then like you're really lucky. Hopefully you learn from that. You see this is what a code review process should be. And I see the benefits of it. And you take that with you throughout the rest of your career. But unfortunately, most folks don't have that. I did. I had a terrible code review process my very first time was, you know, I'm a lot of people relate. I don't say everyone has this experience. But when you just come out on your first like real job as a software developer, even as an intern, you hear about this process. And you're so worried about it, because you're like, I don't want to be critiqued. I don't want to look stupid. I don't want to, you know, prove that I'm not supposed to be in this job. And then you have an experience where you do get your code critiqued and it is very harsh and it is very mean. That could definitely set you up the wrong path. Like you could say, I don't want to do this anymore. I don't like this. Or, you know, some people might be thicker skinned and they're like, yeah, I did write crappy code or whatever. But regardless of all that, I absolutely believe that there's a proper way to do code reviews and that proper way all comes down to communication. ([Time 0:05:24](https://share.snipd.com/snip/0bd49012-47bf-464c-9205-122b7efa1b13)) - **Begin With Friction Logs** - Start by logging team friction points, then set goals before changing tools or guidelines. - Adrienne recommends mapping problems first so solutions align with actual team needs. Transcript: Adrienne Braganza Tacke So once you have that, then I think the four phase process that I talk about can then begin, right? So now that you have those friction points, now you can establish those goals. Like, are we, you know, now that we know what's hard, what are we actually doing this for? Do they actually match? Are we doing this because it's just been in place? Sometimes teams do a lot of pair programming, and the really, really strict formal code review process is actually not needed. It just needs to be something, a lighter version for that For other teams, they've just been going along with the flow. No one's ever really told them what it was for. They don't know what it is. So it's really good to start with what those goals are. Best case scenario is you're kind of hitting those goals after you've determined what the friction points are. Then the next step is just to really go through each of the pieces there, the choose tools, the set guidelines, and refine, but really take a look at it based on the friction points you've Surfaced. So if a friction point is you want two people to accept a review or to be able to look at it, but your tool doesn't allow you to do that, that's a tool bottleneck that who knows? Then you dig down that hole and see why did we choose this tool? Is it still working for our team? Does it not fit how we want to do our process? And then talk about whether it's worth it or possible to change the tool. If there are guidelines that are not in place or ones that are in place that don't make sense, that's another conversation that you need to have with the team and another thing, another Friction point that could be fixed. So if it's misunderstanding on what's a blocking piece of feedback versus not, and people are always fighting on your team about, I prefer to implement it this way. Well, no, I think my way is better. If those are the types of friction points, then maybe it's worth it to say, talk as a team and agree. This is definitely something we want to call out and should block an approval versus not. And then, of course, the refine I always add in there because it's going to change. Your projects change, your teams evolve, tools evolve, AI is here. So whatever you might have decided as a team initially at the friction points of that time, as you start to implement new things and new guidelines, they might not fit or you might need More. And so it's a continuous process to really make it work for your team. So I would start there. Start logging those friction points and then go through the four-phase process of what do we actually want with our code review process? What's the diff between that and the actual goals or the actual friction points we're having? See if the tools fit. See if there are guidelines that are missing or that we can delete and then continue to do that over time. ([Time 0:11:13](https://share.snipd.com/snip/8a60ae6e-7c5f-4340-8841-664288748184)) - **Collect Feedback Safely** - Capture feedback in multiple ways (anonymous forms, notes, offsites) to surface honest friction. - Adrienne urges leads to facilitate collection to increase participation and buy-in. Transcript: Adrienne Braganza Tacke Because, you know, depending on the team and depending on your rapport, like you said, it might not go that well. Another big part is that some people are not comfortable speaking up or talking about these types of things in a group forum. So having a way to capture that information, not just in a, hey, let's have a meeting and talk about all our problems in front of everyone. It's maybe you send it in an email, maybe you capture that in one-on maybe you go to an engineering offsite and everyone writes in a post-it note. There needs to be various forms of capturing this feedback. If making it anonymous makes it better and more honest, absolutely do that. But, you know, sometimes there are teams who are, they're chill with each other. And that's, you're, you know, very lucky if you have that, where if it is okay, then yeah, you have a conversation, you talk about it. And ideally you whiteboard it out and you, you know, write it all down. But I definitely encourage really anybody who wants to pioneer this process and wants to take it, make it better for the team to, yeah, capture all of that and solve it together. That's absolutely something that's a theme in the book. It's not just one person making this, you know, set of guidelines and then everybody follows. The more you have other people's input, usually you have more buy-in from the rest of the group rather than just top-down management. ([Time 0:15:53](https://share.snipd.com/snip/dc881475-d848-47f9-bca3-dd17abe6628d)) - **Write A Team Working Agreement** - Create a team working agreement that defines reviewer responsibilities and comment structure. - Define blocking vs non-blocking items and adopt conventional comment tags to reduce confusion. Transcript: Adrienne Braganza Tacke Sure. I love this. I learned about it. We borrow it. I don't know who the original is, but we borrow it from the Scrum world or the Agile world and any type of project management where it's just this set of guidelines that you as a team agree To enforce. And what those guidelines are could be anything. So from the Scrum world, it's, you know, we agree what the different user story sizes are. We agree on their sprints, their two weeks versus three weeks. We agree on how we're going to treat each other. You can go as granular as you want. You can get as interpersonal as you want. But I thought it was a really great thing to apply to code reviews because there are a lot of different parts, those unspoken assumptions that would be great to put in a team working agreement. For me, there's a lot you could put in there. But if you had to start and you definitely had to put something in there, I would say the most important thing is the reviewer and approver responsibilities and how you communicate in Code reviews. So even that sounds kind of generic. What I mean by that is what are your non-blocking versus blocking pieces of feedback? So if something falls under the lines of a security issue, a code smell issue, you know, straying away from code convention issue, what's the word I'm trying to look for? If this introduces or if it makes code maintainability more difficult, all of these types of smells or things to look for, you would put in a blocking issue list. And then all of the things that a lot of folks tend to agree are should not be blocked, meaning somebody can't, you know, not approve it because you don't fix it. Silly things like formatting, spacing, preferential variable naming, unless you can back it up with an objective fact, like that's going to be different among every team. So if you can have that conversation and agree at least to the most important things of what should be blocked versus not blocked, that's one way to be more clear on communication. And the other part is how to structure your comments. I dedicated a whole chapter to this because it's that important, but I mentioned something called conventional comments. If you're familiar with conventional commits, it's kind of the same thing where you basically are structuring your comment so that it's very easy for the code author to read it and know What to do. Do I need to address it? Do I not need to address it? Is this blocking? It's not blocking. What is this related to? Do I need to make this fix right now? Is this a suggestion? Is it polish? Is it, you know, a lot of the times when we get pieces of feedback, we immediately panic and are like, oh my gosh, I have to work on all of these things. But then later on, when you talk to the reviewer, they're like, oh, no, I just wanted to tell you those things. Like, actually, everything looks fine. So you waste some time worried thinking you needed to make all these changes. But in reality, these were just, you know, things they wanted to share with you. So by adding a simple little tag or comment signal, also what my team use, you can, as an author receiving that feedback, it's much easier for you to be like, okay, these are the things I absolutely have to fix. These are the things I don't have to address. And that makes it go much faster. Those would actually be the top two things I would put in there because the majority of things that people argue about are within that process. It's misunderstanding each other. And then you get into a debate and you're like 27 comments long in a thread of arguing why you should do this and why you should not do this. Or it's arguing about, no, you should approve my PR because X, Y, Z, and then someone else says no. And you haven't decided on what should or should not block it. So those would be the top two important things. And that kind of falls under what is the responsibility of a reviewer and an author. So the most important or the bonus things I would add in there are what does your code review process like actually do? What are the steps? Because that will not only be helpful to your team to reference, but any new team members can now easily get into the swing of things. Even folks who are not new to programming, just new to programming, sorry, that's what I meant. ([Time 0:17:29](https://share.snipd.com/snip/fa8a937f-20f2-452c-966e-7c9d411c38a9)) - **Use Conventional Comment Tags** - Use conventional comment tags to mark blocking, suggestions, or polish so authors know required actions. - Adrienne says structured comments prevent wasted effort and endless debate on PRs. Transcript: Adrienne Braganza Tacke How to structure your comments. I dedicated a whole chapter to this because it's that important, but I mentioned something called conventional comments. If you're familiar with conventional commits, it's kind of the same thing where you basically are structuring your comment so that it's very easy for the code author to read it and know What to do. Do I need to address it? Do I not need to address it? Is this blocking? It's not blocking. What is this related to? Do I need to make this fix right now? Is this a suggestion? Is it polish? Is it, you know, a lot of the times when we get pieces of feedback, we immediately panic and are like, oh my gosh, I have to work on all of these things. But then later on, when you talk to the reviewer, they're like, oh, no, I just wanted to tell you those things. Like, actually, everything looks fine. So you waste some time worried thinking you needed to make all these changes. But in reality, these were just, you know, things they wanted to share with you. So by adding a simple little tag or comment signal, also what my team use, you can, as an author receiving that feedback, it's much easier for you to be like, okay, these are the things I absolutely have to fix. These are the things I don't have to address. And that makes it go much faster. Those would actually be the top two things I would put in there because the majority of things that people argue about are within that process. It's misunderstanding each other. ([Time 0:19:38](https://share.snipd.com/snip/c99127aa-8716-4f30-8694-96a41351d2b6)) - **Automate Low-Hanging Checks** - Automate formatting, linters, and tests so humans review only contextual, creative issues. - Adrienne recommends using AI/tools for first-pass checks but keeping humans for final sign-off. Transcript: Adrienne Braganza Tacke Absolutely style guides should be like the first thing at most teams. That's one of the things that surprises me is that there are still people fighting about like indentation and spaces and you know just little formatting things and I always thought We waste so much time on this, not just for, you know, you fixing it. I know everyone usually despises getting like 20 comments of, oh, you missed. So if there's anything that can be automated, should. Anything you can fix before the code review should be automated. If you have a linter, ESLint, Prettier, if you have static analysis tools, so like Roslyn for C-sharp framework, if you have any of these things, automated tests, so Mocha tests or Dress Tests, if you can run any of these things and fix them before the code review I highly recommend implementing those things first because this is what I call the the low hanging fruit the Things you don't want to waste your time on during the code review and these automated tools will find it much faster and again with the interpersonal thing most everyone was more willing To fix that squiggly line. Like if a machine is telling you you did something wrong, I'm like, you're right, I should fix that. But if someone else is telling that to me, I'm like, I roll my eyes. I'm like, I know you're right, but it just, it feels, it feels worse if somebody else is telling me something like that. I'd rather have something that with all of our ingenuity, creativity, nuance, context, what humans are good at, I'd rather have them spend their time looking at my code, looking for Those issues that cannot be found by automation. I want to talk about that. I want to see some random edge case that I may not have seen because I was so in the weeds of creating this and getting this feature done that you happen to see. And we talk about it. Alongside of that, I know AI is going to be a thing, right? The fact that we are generating so much more code with AI, that's where I'm like, code review is absolutely still necessary for humans. And I still stand by this. I know in the book, I go, you know, I'm not against AI code review tools. They're getting better. They're definitely better than when I published the book, but it's still not there. The thing is, you want to maybe use them for like a first pass. So absolutely use the code review tool to surface, again, those low-hanging fruit, those suggestions, those easy fixes. Maybe it's a typo. Maybe it's, you know, something that fixes the structure of code to make it more readable. Absolutely use it as a first pass. But then as a team, you need to monitor and see, is the use of this AI tool, again, is it achieving the goals that we want? Are we spending more time correcting or, you know, getting false positives from a code review tool versus it making it faster for us versus it surfacing things that we don't see? Those are the kind of new questions that we have to ask ourselves as we start to integrate AI tools into code review. One thing I definitely support is keeping structure in the code review process. So I talk a lot about being very, very explicit in our PRs, you know, make sure the title can be well understood and you don't even have to go into the description to know what this is about. Keep it atomic, make it actually manageable to review, link things, put things to documentation and using automation and tools to help you do all of that because that's the extra work That unfortunately a lot of software devs don't want to do. There are a lot of folks that are, you know, sometimes we're feeling lazy, sometimes we just don't care. But if that helps counteract those feelings to make sure we're doing better and just being better software developers, I'm absolutely for using automation and tools like that to keep Consistent, to add explicit information in our PRs and to, yeah, do the first pass. But I think for fully taking care of the code review, absolutely not. ([Time 0:24:04](https://share.snipd.com/snip/651ffab0-fd11-4e27-ad78-a64e9ceaf6a9)) - **AI Helps But Cannot Replace Humans** - AI tools can speed reviews but lack team/project context and can't replace human judgment. - Adrienne views AI as a helpful first pass but insists on human final approval. Transcript: Adrienne Braganza Tacke I want to talk about that. I want to see some random edge case that I may not have seen because I was so in the weeds of creating this and getting this feature done that you happen to see. And we talk about it. Alongside of that, I know AI is going to be a thing, right? The fact that we are generating so much more code with AI, that's where I'm like, code review is absolutely still necessary for humans. And I still stand by this. I know in the book, I go, you know, I'm not against AI code review tools. They're getting better. They're definitely better than when I published the book, but it's still not there. The thing is, you want to maybe use them for like a first pass. So absolutely use the code review tool to surface, again, those low-hanging fruit, those suggestions, those easy fixes. Maybe it's a typo. Maybe it's, you know, something that fixes the structure of code to make it more readable. Absolutely use it as a first pass. But then as a team, you need to monitor and see, is the use of this AI tool, again, is it achieving the goals that we want? Are we spending more time correcting or, you know, getting false positives from a code review tool versus it making it faster for us versus it surfacing things that we don't see? Those are the kind of new questions that we have to ask ourselves as we start to integrate AI tools into code review. One thing I definitely support is keeping structure in the code review process. So I talk a lot about being very, very explicit in our PRs, you know, make sure the title can be well understood and you don't even have to go into the description to know what this is about. Keep it atomic, make it actually manageable to review, link things, put things to documentation and using automation and tools to help you do all of that because that's the extra work That unfortunately a lot of software devs don't want to do. There are a lot of folks that are, you know, sometimes we're feeling lazy, sometimes we just don't care. But if that helps counteract those feelings to make sure we're doing better and just being better software developers, I'm absolutely for using automation and tools like that to keep Consistent, to add explicit information in our PRs and to, yeah, do the first pass. But I think for fully taking care of the code review, absolutely not. For, you know, even going so far as let's just pass it to, say, CodeRabbit, for example, and then it approves it and it's all automated and there's nothing in there. Absolutely not. We're not there yet. I actually even spoke to some folks on the CodeRabbit team. And I mean, I don't know if they're going to like me saying this, but they did say, you know, we're absolutely in support of humans still being in the process. Tool so that a lot of those friction points of maybe trying to get feedback faster from the reviewer, of explaining things, of surfacing easy suggestions to fix right away, those types Of things, we absolutely built it for. And obviously, it's still going to take time to also learn how our team works, how our project works. That cannot be replaced at least quickly by AI. ([Time 0:25:54](https://share.snipd.com/snip/71210c63-38a8-448e-8202-a001ae210e6b)) - **Reviews Capture Context And Why** - Code review's value includes oversight and sharing the 'why', not just bug catching. - Adrienne warns overreliance on CI or metrics can hollow out the review's purpose. Transcript: Adrienne Braganza Tacke Yeah, I think a lot of folks miss that part is what I've seen lately is a lot of folks are introducing AI code review tools because they are being measured by metrics that are like misused. So that's one thing I kind of touch on, but that could be its own book. But, you know, if you're if you are reading or monitoring the performance of your devs based on some arbitrary single measurement of like, how fast did you close your PRs or how many did You review? And you only take that single measurement into account without looking at the whole story. Reasons why some devs I've spoken to are like, well, yeah, we're very much in support of the AI code review tools because it's going to help me review more faster with the goal of, you know, Gaming that metric. So it's really important to kind of, you know, remember that these might be the reasons for why we unintentionally make it worse for ourselves, even though we think we're doing the right Thing. And just take a step back from those types of reasons. Always go back to like, what was the whole point of why we wanted to do a code review in the first place? And this fits in into the wider ecosystem of like a fully robust CICD pipeline. You know, a lot of folks are like, well, I have all that automation in place. Like, why do I even need a code review? You know, it's going to be caught. Or if something breaks in the staging environment, it's okay. That's not the point. The point is there still needs to be some sort of oversight of knowing what's going on in your code base. And for most teams, the only place where that happens is the code review. Otherwise, it's when you're pair programming, but then how do you share that knowledge across the team rather than just the two that were working on it? And again, if you have to reference something in the future, even if it's yourself six months from now and you're like, what did I do here? Why did I make this change? I don't remember. I don't remember what happened two weeks ago. So the more documentation that I have, not just of what is happening, but why, a lot of what's missing and that's what takes so much longer to get back into a code base, I argue, is because You're trying to understand why something was done the way that it was done. And when you go back into it, you're like, you know, maybe you try something that was already tried and nobody's documented why that implementation didn't work. And there's some quirk. And so, yeah, I digress. I'm going on a tangent now. But you definitely just need to take everything into moderation and see what those initial goals were for or why you established a code review in the first place. ([Time 0:31:38](https://share.snipd.com/snip/c57d6484-2ec0-411f-aa77-019c3fc31ea9))