How to Make an Unforgettable Code Review? Guide for Authors

What is Code review?

Code review is an integral part of any software development process. This is the very first barrier to selecting only quality code. A way to prevent various bugs related both to the business logic itself and to the basic performance of the application. As part of this process, code written by one developer (author) goes through a complex validation process from one or many other developers (reviewers).

Why do we need it?

Let's figure it out, why do we still need to complicate the lives of developers and increase the time it takes for new features that are expressed in the program code to get to production? What are we winning from it?

Another pair of eyes. During development, you become too close to the code are you writing and could not notice, or take some things for granted. A person from the outside could critically assess the quality and correctness of your decision. Ask questions that would bring you on the right way.

Other experience. Your reviewers may have different experiences than you. Someone is in the profession and knows more, someone worked in this area before you and knows how everything works there, and someone could have been involved from another team, department, or profession and can offer a non-standard solution or generally see things from a different angle.

**Knowledge transfer.**Even other things being equal, even when you really have the best and the rightest solution, it is important to know how you came to this decision. Why it should be done this way, and how it works. After all, in addition to developing the system, it would be maintained.

Code review preparation rules

Of course, good code review preparation starts with writing good code. I would not name patterns, reference clean code rules, or something like this but want to concentrate your attention on more basic things below.

No “by the way” changes. All new and updated lines of code must be connected exactly to the area where you working now. Do not try to fix anything not related to your task. Breaking this rule and adding one more zone to check it is like bringing one more extra variable in an already not-so-simple math expression. It could bring confusion and create noise for the reviewer, spread his attention, and make him miss something. Try to concentrate all his attention on one small piece of recently changed business logic. It would be much clear for the whole team if you would create a separate ticket with detailed tech notes for handling extra not related fixes.

Document code. Comment on any complex and not obvious things. Do not hesitate to write long names for variables. Know the code style guides of the project and of the language you are writing. Update already existing MD files, and external documentation according to changes. And do not forget the words of Eugene Zarashaw, a Facebook engineering director,

Effectively the code is its own design document often

Commit per each stage. The next big thing on your way to the code review is making a great commit and here are a couple of rules for them below. Each stage of implementation should be presented as a separate commit. It is a good way to structure your PR and helps the reviewer to understand how you were thinking. Also sometimes you could request a code review for a specific commit, e.g. for core functionality, while it is direct usage is not fully integrated with other parts of the project.

Meaningful commit message. A commit message should always make sense. Treat it like a unique description of what is stored inside. No one-word messages like “fix”, “done”, ”change”, etc. If something was fixed just describe what or maybe why. If you are working with some task trackers put the ticket identifier in a commit message. This would allow binding all those commits to a ticket on a tracker side.

Smaller is better. Putting more attention to decomposition in the early stage - on planning, and splitting into sub-tasks, would ten times pay off on code review speed. Here is how it works, the size of code (the number of files & changed lines) on PR increases exponentially reviewing time. There is no golden rule for PR size, but my personal recommendation and the number that was found during the Cisco code review research is the number between 200-400 lines of business code lines. Business lines of code are the code that affects the logic behavior and end results for the user. E.g. empty line, documentation comment, or any other comment if they would be removed from the end build would not change application behavior.

Automate all routines. Automate whatever could be automated. Introduce quality gates in your projects locally or in the cloud, but better both of them. Local one could block commit creation or push into a remote repository. Cloud quality checkers would block the merge of pull requests into other branches. Quality gates should cover linting, styling, and running all kinds of tests (unit, integration, e2e, and others). Integrate with code analysis services for detecting code smells, bugs, and potential vulnerabilities. Author and revivers should spend their time discussing performance, security, and maintainability and never on indents size, tab vs spaces, camel case vs snake case, etc

Structure pull request description. The description is the cover for the whole PR. Put here a summary of what was done - a short bullet change list. Clarify possible behavior, and reference requirements in a task, and provide as much useful information as possible (charts, screenshots, payloads, links, etc) whatever would simplify and speed up the code review process.

Author - the first reviewer. Last but not least, an author should always make a first code review before the real reviewers would be assigned. Try to abstract and be critical of the code in front of you. Ask questions and then answer them do it like a reviewer with absolutely the same tools, e.g. comments in pull requests. Your goal is to cover all possible FAQs so other receivers would not need to ask and wait for your response.

Conclusion

A good code review starts even before the first line of code was written, but on a stage of discussion and decomposition of the task. High-quality preparation of pull requests increases its speed of passage at times and simplifies life for both parties. Value the time of others and they would value yours.