In this article, we'll unveil some easy yet often overlooked techniques that helped me impress my code reviewer. However, prior to that, it’s crucial to make sure that we’re well-versed with the concept of code review and what does it entail? Allow the internet to help me here,
Code review is a software quality assurance activity in which one or several people check a program mainly by viewing and reading parts of its source code, and they do so after implementation or as an interruption of implementation. At least one of the persons must not be the code's author.
The Golden Rule
So, first things first, let's remember the golden rule, value your reviewer’s time.
Speaking from personal experience, some people treat their code reviewers as their very own personal quality assurance technicians. They put zero effort to find their own mistakes. On the contrary, for reviews to work properly, you need to make it a two-way process where you and your reviewer trust each other. Therefore, you need to make sure that you have kept your end of the bargain as well, and you don't make your reviewer feel like they're doing all the work.
This brings me to the very first principle.
Principle 1: Review Your Own Code First
Before creating a merge request and asking whoever it is that you ask to review your code, make sure that you go through your code first; and don't just check for mistakes, read the code as if it's your first time, and mark any areas that you find confusing. Everyone has a pattern of mistakes that they tend to repeat inadvertently, but you want to be better; look for such patterns(if any), and try to make your code robust enough to sustain these mistakes, or even better try to prevent them altogether!
You should know that making mistakes is not the end of the world, it's a part of every programmer's journey. However, if they happen too frequently, moreover, if you keep repeating the same mistakes, this shows sloppiness and tells your reviewer that you don't value their time.
Principle 2: Automate The Easy Stuff
Neither you nor your reviewer should be wasting time in looking for a missing curly, brace, or fixing the syntax of your code. That's what automated tests are for! These tests should be part of your team's standard workflow and all the code reviews should be done after your code passes the automated tests in a CI/CD environment.
However, if the team/firm that you work for, doesn't work with CI/CD processes(like mine doesn’t), there's still an effective way that I use to make sure that our development environment complies with proper conventions. The way is to use linters and formatters.
Well, coming back to my point, as I pointed out earlier, code reviews are not meant to find syntactic bugs; your reviewers expect better from you.
Principle 3: Answer Questions With Code Itself
So, I was a new hire in this company and I was assigned a project that I was supposed to start from scratch. During one of my initial code reviews, my reviewer asked me questions about some predefined constants(with some specific values) that I’ve used in the code, understandably, as he had no idea about the context of the code as it was an entirely new project. To answer his queries, I scheduled a meeting with him to explain to him the reasons for my decisions. As expected, everything went well and my reviewer was convinced with all my arguments, and we kept on working in the same manner.
Fast forward six months later, there was a new hire in our company who was assigned this same project that I worked on before. Now, while going through my part of the code, this new girl had some questions for me, those happened to be the very same questions that my reviewer used to ask me during our initial code review sessions. Well, it's already been six months, who remembers everything they did six months ago!!! Moreover, it wasn’t that I “had time” to document my code at the time(like most of the developers).
The point here is, when your viewer expresses confusion about how the code works, the solution isn't to explain it to that one person, you should be capable of explaining your code to anyone and everyone. Now, I’ve realized that the best way is to let your code answer all the questions by itself, i.e., try to write code that is self-explanatory. Code comments are surely an acceptable solution, but they're inferior to the code that naturally documents itself.
Principle 4: Atomic Commits
Sometimes, while working on implementing a new feature, we tend to revisit the old code that we might have written months ago. However, being an evolved developer in that duration of time, we question our old techniques, and now, having learned some newer and better ways to handle things, we think to ourselves, while I'm already here, making some changes to this file, I might as well fix this other thing. However, what we don't think of, is that because of this move, our code-reviewer is going to have a hard time figuring out what changes serve goal A and what changes serve goal B. Therefore, it is really important to make your changes atomic.
Decoupling unrelated changes will allow you to send different pieces of code to different people and have them review those changes simultaneously.
Principle 5: Functional And Non-Functional Changes
The next technique is kind of the parent technique of the previous one, try to separate functional and non-functional changes. This is the one principle that I've violated, I don't know how many times, and I'm afraid that I learned it the hard way!
For instance, you make a small two-line change that affects the behavior of the code, and then you decide to format the entire file. This means that your code-reviewer will have to rummage through the hundreds of lines of white space changes just to find those two lines of functional code or change buried inside, that actually needed to be reviewed. Isn’t that annoying?
Principle 6: Respond Graciously To Critiques
Though I feel this might be the most obvious technique, it’s still worth mentioning. There’s something that I learned in theory about human nature from self-help books, but with experience, I can vouch that this something is most true for any human you seek help from. When you demonstrate an appreciation for constructive criticism, people put in more effort and they provide better feedback because they know they can count on you to take their feedback seriously. This statement applies to you and your reviewers in its entirety.
Principle 7: Be Patient Even When It’s Your Reviewer Who Is In The Wrong
Try to question your ways, even if it's your reviewer that's mistaken. Try to think of it this way, if your code-reviewer misread a certain part of the code, can others make the same mistake too? Does the reader really have to exercise that abnormal level of scrutiny to make sure that a particular bug isn't there? Is the code really so convoluted?
Look for ways to refactor the code and add comments wherever possible to make the code intuitive to everyone and easy to comprehend.
If the confusion stems from a particular piece of code or a particular feature specific to a language that you know about, but most people don't seem to be very well-acquainted with, try to rewrite the code using a more commonly practiced way, so that it's more obvious to the rest of the members in your team.
Principle 8: Ask for Missing Information Artfully
If you receive a note like, “This is confusing!”, from your code-reviewer. What would your first response be? Well, for most people the first instinct is to ask a follow-up question, which would be something like, “What's confusing about it?” But trust me, this can come across as a little grouchy. Instead, a better follow-up question to gather more information from your reviewer without sounding grumpy would be to simply ask, what changes would help!
By the time, your reviewer responds, you can give your code a second look, usually, there's always something or the other that you could fix to improve the clarity of the code. A revision would communicate to your reviewer that you're open to changes(even if it wasn’t exactly the one they had in mind).
Well, these were some techniques that I learned in my career so far, for an easy and smooth code review. If you think that I missed something or if you want to share some more techniques that have helped you in the past or that you learned recently, I would love to hear them down in the comments. I hope the information provided in this article provides value to you. Thanks for reading. Happy Learning!