How to and How not to, do Code Review

As someone who gets thrilled every time when I see a brilliant piece of code, I always tried to achieve that peak code quality and perfect repo in my projects. Working on multiple projects and seeing your projects with perfect, performant code with impeccable variable names, flawless performance come to a huge failures made me realize that you don't have to be hard on the code review process and made me understand the mistakes I made when reviewing other's code.

1. Don't insist on coding style

Don't get me wrong, your project should have a coding standard and style. Instead of manually making sure it is followed, automate it. Make use of git pre-push / pre-commit hooks. Test it via CI/CD tools to make sure that each PR is tested independently of the developer's environment.

Use a linter and code beautifier of your team's choice. If  your project is JS, use eslint, prettier, etc, if it is python use pep8 or pycodestyle. If you want a custom rule which you can't find in any of these linters, write your own shell script.

It is OK if the variable name is long, or you can come up with a better variable name. As long as the code is readable and code is making sense, it is fine, let it go.

2. Focus on things that matter

Instead of going line by line, check the overall logic, check flows in the logic, structure, maintainability and re-usability.

Having a perfect code may give you a short term ego boost. But in the long term, the time you spend on that is just a waste. Instead of focusing on that, try to build something new or fix a couple of bugs.

3. Multiple ways of doing things

As programmers, we always see different methods of doing the same things.
If a choice is subjective, prefer developers choice and not impose your  preference. It is common to have multiple ways to do same thing. Avoid  asking "why not this way" unless there is a demonstrable advantage. [1]

4. Ignore minor issues

As long as it is not causing a bug, leave minor issues aside. Interfere only if it will cause a bug. You are not trying to write Linux Kernel. It is OK to have some bad parts of your repo. I am pretty sure even Linux Kernel will have some bad code, even after Linus's strict code review.

5. Check backward compatibility

Make sure the new changes won't break any of the existing code. If there is a change in a function, make sure the changes don't break code in all the places it is being called.

Most of the time, a person working on a single feature may not be familiar with all parts of the project. So as a reviewer you may be able to bring that to the author's attention and ask to check and test other parts.

6. Clarity on your comments

For every comment that you make, make sure there is a clear action to be taken. It should be clear what you expect to happen. Just stating your opinion is not enough. If possible give code snippets. Then it becomes a team effort than a judging exercise. [2]

7. Last but not the least, Be nice

Don't be a jerk, be nice to the person who spent time to write the code you are reviewing. The code you are reviewing is written by another human being who has their own opinions, be considerate, don't push your ideology down his or her throat.

Have comments? write to feedback@jishnu.xyz

Notes

[1][2] Santhosh Thottingal helped me frame the point 3 better and introduce the 6th one..