January 06, 2021

Code review is considered to be the #1 practice a company can use to improve code quality. But its benefits extend far beyond that, while its drawbacks can be managed by following best practices guidelines, all of which we are about to explore here.

Are code reviews challenging?

Reviewing code is not that easy, it can be a pain in the butt actually. Most of the time you find yourself busy and enthralled in your tasks and then you have to stop and switch context. The cost of interruption, for a developer, is on average higher than 23 minutes so you have to plan your code reviews with intention and attention. The context switching brings in the need for greater memory allocation and that becomes taxing on overall energy and productivity. Code reviews can become a chore and that’s when you need to frame your mind, remind yourself why you’re doing this and what the benefits are, and also use all the tools in your arsenal. And by tools I mean linters and code formatters that can take away from the load of code reviewing.

Another challenge of the practice is that it can affect interpersonal team dynamics, few people find pleasure in their code being critiqued and nitpicked and it can also result in people attacking each other. For this, it’s best to cultivate a culture of code review and understand that delivering feedback in a respectful and palatable manner is a celebrated skill.

To reduce sensibility to critique, you should stay open to being challenged. This maintains agility, freshness, and the openness necessary to learn and grow. It’s an honor when someone is willing to review your code. And if your sensibility to critique can’t be tamed that means it’s time to become a better developer.

When everyone in the team does code reviews and sees their importance and role, the adoption of the practice will prevail.

I believe that as time passes by and the team matures, code reviews should end up taking less and less time. The standards and expectations should be more obvious to everybody, the code base more familiar and the teammates should have learned from one another.

Psychologically speaking, code reviews tap into what turns out to be a useful human trait, the predisposition of seeing someone else’s mistakes a lot easier. This principle is prevalent in human life. Why not harness it in software development also? Also when you work on a task, you have the tendency to focus your attention on the problem at hand and therefore put your mind into the box of the task. Sometimes it takes another set of eyes to see outside that box.

What’s the point of code reviews anyway?

The most imperative reason is that life is short, you do not want to spend your life trying to understand badly written code, you want to hear music when you read code, not a metal pot falling down the stairs. Code reviews are your first chance to raise code quality, to make sure you don’t end up working on a mess of a code base. Use this chance! Code reviews are a critical part of the development flow.

It’s one of the best ways to accumulate knowledge. The best way to learn how to code is by reading code and understanding it. As a new member of a team, as a junior, reviewing code it’s your road to success. Usually, the more senior members of the team are busy and after a lot of years on the ‘battlefield,’ their patience might be limited. Use code reviews to learn the project, the style of work, standards and to avoid asking questions that you can answer yourself by looking at the code. Thus you become more resourceful, a necessary skill for a developer.

Increase the ‘bus factor’. You don’t want only one of your team members having too much knowledge. If that team member got hit by the proverbial bus then no one on the team would know anything about the code. Code review is the opportunity to take ownership of a larger part of the codebase and ensure you have a general view of how things work and are connected to each other.

Code reviews contribute to earlier detection of issues and prevention. This ensures that the development will be underway on a stable code base which is then reflected in the speed and correctness of the implementation. The overall health of the codebase does not diminish over time.

Having a main reviewer can save a lot of issues down the line. Somebody who reviews code from every part of the app will be able to foresee any major sources of bugs, problems in the design, detect missing functionality, see any necessary refactoring, reduce code duplication, enforce standards.

Being subjected to code reviews might just be the thing that pushes you to become a better developer. Feel the burn, feel the peer pressure! Work those muscles!

What defines a good code review

A good code review starts with the author of the code

Your intention should be to make it quick and easy for others to understand the code you just wrote and decrease the wait time for your code to be reviewed and merged.

The first rule you need to follow is to keep your PRs (pull requests)/review requests as small and as cohesive as possible, one issue – one pull request. If your task requires many changes in many files, see if you can create multiple smaller PRs.

Provide descriptive titles, comments. Avoid commit comments like ‘changes’, ‘code adjustments’, ‘small edits’ when possible. Having multiple descriptive commits, one for every issue you’ve tackled on accomplishing a task, can actually be a learning opportunity to others, by providing more context of what happened during the development and what changes were necessary for every issue.

Don’t forget about adding comments in the code when needed or encapsulating code in functions with descriptive names. Usually, comments are also necessary when you do something a bit more unusual than regular (like fixing a weird bug in an unorthodox/not using the framework as intended manner) or for a complicated piece of code. The ultimate goal is to have your code written in such a way that it can be read like a newspaper, with the headlines and subheadlines being your methods and submethods.

Absolutely test your code before marking it as ready for review, an experienced reviewer will figure out that the code is not tested and that is considered wasted time for him/her.

Review your code yourself. After you’ve tested it and you feel like the task is finally done, go through all the changes yourself, I bet you’ll be able to find some clean up you need to do or you realize that the code is not that easy to understand and make some tweaks, or you can even spot some corner cases you forgot about. The self code review is usually more effective the next day.

Pay attention to the review comments provided on your colleagues’ review requests, learn from them, don’t end up in the situation where the reviewer has to provide the same feedback to you.

Follow your review requests, don’t expect the reviewer to let you know every time you have code review comments.

Be patient, don’t expect immediate review every time. Your colleagues are busy too. Do not consider code reviews as a safety net for not testing and not being diligent enough.

Create your brand, be the person that always tests his/her PRs, be the person that always takes into consideration best practices, performance, security, code quality. When you create your brand, reviewers will know what to expect from you and that speeds things up. If you do these, your teammates will admire your professionalism and the way you’ve made their workday a delight.

What should you watch for in a code review?

Your contribution to a code review can vary depending on your relationship with the task that was implemented, your qualifications, and your deadlines. Sometimes your contribution can be just that of learning. Your actions might be one, some, or all of the ones stated below.

The learning steps:

– You should get to know everything you can about the task that was implemented on the review request: get acquainted with the way the task is written, understand the specifications described, understand the business logic, remember the functionality for later reference. If it’s a bug, take notice of the kind of bugs the app is dealing with, remember it, so when you bump into something similar you know where you can find your source of inspiration. – You should get to know how to test the functionality that was implemented – Understand the changes and the ‘why’ behind the changes

The code improvement steps:

– Determine if the task was implemented correctly – what is the code doing, does this break any existing functionality, does it introduce new bugs, has it missed out on some corner cases?

– Check the code correctness, cleanliness, adherence to best practices – naming, structure, error handling, DRY, standards, missing code comments, is it over-engineered or needlessly complicated, is it easy to understand, is something deprecated and needs to be updated, is it obvious that this can be done better?

– Consider non-functional requirements: performance, security, scalability, accessibility, user experience and all the other attributes that impact not just the piece of code you are reviewing, but the entire product.

– Extrapolate. This can mean anything. Oftentimes code reviews can spark your creativity, and can trigger new ideas.

Other tips & tricks

Don’t make the code the best that it can be, aim to bring the code up a level or two,developer patience is finite.

The worst code review you can do it’s actually the one where you hit Approve without any involvement, no learning, no acknowledgement, no respect towards others who do them.

Find a balance between noise/flow interruption and valuable feedback. Beware of bikeshedding/nit peeking/things that don’t really matter.

Don’t point out 50 issues at once, it’s too much, review in rounds.

Read the code in full, make draft comments, double-check, ask questions if needed.

Suggest alternatives, explain your understanding, give some background to why you think something is wrong, provide links to online sources.

Sometimes the author simply doesn’t understand your point of view. In this case, the resolution can be to actually approve the code as-is and log a refactoring task for later and assign the task to someone else. When the implementation is done the initial coder will have another chance at understanding the approach.

If you pay attention to the task and how long it takes the developer to implement it, you will know if you need to give that review request some extra attention. If the time of implementation seems too short you can infer that the coder probably didn’t test enough or forgot some corner cases.

Trust your intuition. Oftentimes you scan some code and you immediately sense something is not right but you don’t know what yet. Do not ignore that feeling, it’s the first clue that you won’t get away easily with this code review and changes have to be made, if not now it will surely come later as a bug or something else, but it won’t be something good.

Develop your brand as a reviewer, win the trust of the team, set a track record for impeccable reviews. Are your reviews for real or just a quick approval and getting back to your tasks? Code reviews should be an integral part of your tasks. When you approve a piece of code it should mean it’s ready and it’s not absolutely necessary for the entire team to review that code in detail also, thus saving time and splitting the workload. No matter your experience, there’s always a way you can contribute.

How to comment

Remember that written words sound harsher than when you hear them. You have to develop your skills of providing feedback in a pleasant manner and there are some tricks on how to do that.

Frame your mind for review, assume good intentions and competency, this will help with maintaining your composure. Be aware of any cognitive bias you may hold. Ask yourself how to approach the conversation with tact and empathy to reach a positive outcome, how will you help the author learn.

People like to feel in control of their work, they don’t like to be bossed around, so when you phrase your feedback as a request/ suggestion, not a command, people can maintain that autonomy.

Encourage people to make corrections, be polite, suggestive, specific rather than aggressive and sarcastic.

Be open to follow-ups.

Make compliment comments, offer sincere praise.

If the comments pile up, do a summary. Deliver some of them to the author in private to set a collaboration tone. Go over your comments before send-off, edit them if needed.

When it’s needed and things don’t progress, take your code review to a call or face to face.

Prefix nit-picking comments to let the reader know they are minor issues.

Don’t use You, this brings in the ego and sounds accusatory, use a passive voice.

Examples of comments:

Bad comments	Good comment
You misspelled this Change this Wrong, it should be x Why is this done like this	There is a type for x This can also be implemented like x and it will help with y Please provide some details for choosing this approach This can be changed to x You forgot about x

Kindness goes a long way, but like everything in life, too much of a good thing is a bad thing, you have to find the equilibrium line between the yin and the yang, between kindness and assertiveness.

And in the end, given that we’re all humans, code reviews might be more than just about code, it’s about adding human interaction, bonding, learning, sparking discussions, breaking monotony.

Thanks for reading and Happy code review to you all!