We do it every day, why not become better at it?

Code reviews are like the penultimate stage for your and other people's code, before it's shipped out to the world. So it only makes sense to have a good grip on some of the basic etiquettes one should follow while doing code reviews and also while submitting code for reviews. In this small 5-7 minutes journey, we'll try and cover most basic things that we should keep in mind when we are the review-er or the review-ee. Let's get started!

Code Review Tip #1: Settle on style early, and automate whatever you can!

There are certain style choices every team has to make regarding the code-base, which should be decided as early as possible and conveyed throughout the team. Things may change over time, but it's always good to have a starting point instead of people willy-nilly doing things all over the place. These may include things such as

• The timeless "Tabs vs Spaces" debate.

• Having those curly braces on the same line or a new line.

• If you are a Javascript developer, using or not using semicolons. Unsolicited personal comment here, you're a monster if you don't use semicolons!

Next comes automating things which prevents human errors, and saves a huge chunk of time. This should include things like

• Linting and formatting

• Catching unused imports and variable declarations.

Code Review Tip #2: Always be polite, go beyond just finding mistakes and appreciate good practices!

Let's see two sentences we often see in any code review:

If you were a developer, and getting your code reviewed, which side of the table would you prefer as comments? Right side for sure. So why not put yourself in those shoes while giving review comments and take a more benevolent approach while writing comments yourself?

And why stop there? Why not drop a comment for appreciation when you see a great piece of code someone wrote? Or maybe a Junior developer who made some mistakes during his last submission put up great code this time around without the previous mistakes? This kind of appreciation might be rare in practice, but there's no wrong date when it comes to starting a good practice! Try it within your team today.

Code Review Tip #3: Clear descriptive comments and Sanity checks!

Always try to be specific and comprehensible with your comments and avoid jargons where you can. If you are suggesting a change that is small, you can even add examples to convey your point. This makes it easier for the other party to understand and helps avoid a long back n forth on the same issue.

Also when in doubt, ask away! If you're looking at some code and you want to suggest changes, but you're also unsure about the intent behind that code itself, it's better to check with the Author and clarify. If you don't do this, it can lead to unnecessary waste of time and a tinge of annoyance on the part of the Author.

Code Review Tip #4: Know when to take things offline.

If you've had a Back n Forth on a review comment thread with someone for more than a few comments, and things seem to be going nowhere, it's better to reach out over a quick call/personal message to discuss things. Rather than having an all-out battle of wits in public view. And it's also easier to convey your message personally instead of doing it on a comment thread. So keep this in mind!

And with that, we conclude the reviewing other people's code part of things. Next, we'll discuss the equally important other side of the coin, Submitting code for reviews.

Code Submission Tip #1: Always give good descriptions while raising a Pull Request.

Nothing beats this approach of adding a comprehensive description with a Pull Request. Let others know What the changes are, What the changes do, and Why are the changes necessary. Granted most teams/organizations will have their own set of rules for this, but in general, it's good to have a thorough description. You can also add screenshots/videos and a Jira ticket along with the description making it easier for people to take a quick peek.

Code Submission Tip #2: Small Chunks make for easier reviews.

I know we've all worked on features or changes that required us to push code with changes in 1100 files at once. We also know it took 7 people to review that Pull request and 81 days to resolve all the review comments. While I may have taken the liberty of exaggerating for effect in this example, large chunks of code are difficult to review and merge. So whenever possible, try and push changes in smaller amounts.

Code Submission Tip #3: Comments!

During development we tend to leave comments in code explaining the intent behind a function, or why that error callback has been left with a solitary console.log

But this is not always possible and is also inconvenient at times. So while making changes to existing code, leaving comments in git diffs is a great way to notify the reviewers about a specific piece of code. This way, you answer a potential question about that function you completely removed without the other person having to ask it. Saving both of you some precious time.

So yeah, those were some points I think will make your life easy as the Author of a Pull Request. And have a similar effect on the person on the other end reviewing your code.

Conclusion..

I don't think there's much to be mentioned here. The same people who avoid reading documentation before using a new framework or library aren't sticking around to reading the conclusion of some article on the internet. But I'd still like to thank that one Geek who stuck around till the end. I also hope this article helps people become more efficient in their work. With that, I'll end it here. I got some Pull Requests to review, and some review comments to fix myself. And no, I may not follow all the etiquettes I mentioned here. After all, I only partially read the documentation of any new library/tool I use too! Cheers!