Code Review Best Practices For Authors (Code Review 2/3)

In the previous blog post, I wrote about why you should do code reviews. In this blog post, I wrote about how code reviews should be created. I wrote hints for authors (programmers) whose code is being reviewed.

Keep It Short!

This is the most important rule for a programmer who is creating a code review. It is so important rule, that I even put an exclamation (!) mark to it. Unfortunately, this happens a lot, especially when a team is beginning to do code reviews. What is a short code review? SmartBear suggests 200-400 lines of code (LOC) and I agree with that.

Reasons why long code reviews are bad:

  1. They are difficult to understand,
  2. The reviewer doesn’t really do the code review.

The longer your code reviews is, the more difficult it would be to understand for the reviewer. And if the reviewer can’t understand what you have done, the code review will lose its meaning. SmartBear has made a study that when the code review is longer, the reviewer will find fewer errors. Because we want code reviews to be effective and find errors, better to keep code reviews short.

Explained how LOC affects to code reviews: more code, fewer errors found.

More significant reason to keep code reviews short is that if they are too long, the reviewers won’t even do the review. It will be only a formality. And little by little they will ignore reviews, and that would be the end of code reviews.

Reviewers don’t always feel “Yes, code review!”, because review will take time from their current work. By keeping reviews short, you help reviewers feel more comfortable for reviewing: “Ah, new code review. I will do it now because it will take only 30 minutes”.

What to Do If Code Reviews Are Too Long?

We all know this: code changes tend to be too big. Thus also code reviews tend to be too big. It is a sign that your work is just too large. What to do? Simply split your work into multiple tasks. When you realize that your code changes are too big, stop coding, and think how you can split your work.

For example, if you have a Jira ticket, split it into subtasks or smaller tickets. And put first one to review. For example, if you are working with REST API split it to a controller, business logic, and data layer.

Pre-Review Your Code

Remember to pre-review your code before submitting it to a reviewer. If you use review tool (which I really recommend), it will nicely show your code changes and you can make final fixes. For example, you might have made some file that you don’t use and the tool will show it and you can delete it. Or there is some commented-out code that you can remove. Don’t let reviewers find these trivial issues and let them concentrate on more important things in your code.

Usually, when I think my code is ready for code review and I start pre-review, I find surprisingly many improvements to my code. Code review tools are a great help in these fixes because often you don’t remember all code changes you made and tools will show all your changes.

Pre-review (don’t forget fixes!) will help reviewer’s work a lot because most of the improvements are made in this phrase.

Don’t Take Comments Personally

Review comments are one of the main things developers are afraid of and thus even don’t want to include code reviews in their process. In worst case reviewer’s comments can be too personal, which isn’t good. (Reviewers, remember to be polite!)

Whatever reviewer has commented, don’t take it personally. Usually, a reviewer does not mean anything bad. Or maybe you are overreacting or misunderstanding comments. Take comments without emotion.

Sometimes reviewer might want you to make corrections. Don’t give up, think and learn from those comments. The reviewer has just made his work. And it is better, and cheaper, to correct code now. If you disagree with the reviewer, clarify why you disagree and talk to the reviewer about it. The reviewer isn’t always right.

A classic picture of code reviews.


My code review best practices for authors are:

  1. Keep it short,
  2. Pre-review your code and
  3. Don’t take comments personally.

1 and 2 will serve the reviewer and make his work easier and more comfortable. 3 is for an author. With these three key points, you will improve code review quality a lot.

This blog post continued my previous blog post about why you should do code reviews but concentrated on how you should do code reviews. In next blog post, I continue writing about code review “hows” from the reviewer’s point of view.

Blog Posts in This Series

2 thoughts on “Code Review Best Practices For Authors (Code Review 2/3)

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s