In this post, I’m gonna introduce a very important practice in Software Engineering: code reviews.

Overview

• What is a code review?
• Why
• General aspects
• Best practices
  • As the author
  • As a reviewer
• Biases
• Conclusion

What is a code review?

If you are a developer, no matter how experienced you are, you’ll make mistakes. Code reviews are a practice in Software Engineering that in general, help developers to find defects, design problems, assure best practices compliance and apply knowledge transfer before delivering code.

I really enjoy code review sessions, so I always try to bring this practice to every company I work for. It’s great for learning new things, share opinions and give great feedback!

Why

We want the best code as possible to be delivered. Code that can grow organically, following the good principles of Software Engineering.

• Defects: During a code review, we can find if something was misunderstood, even communication issues.

• Design problems: it’s quite common to think in solutions and forget dark parts of the problem. This is a good time to find design issues that, maybe not now, but in the near future can cause problems. This is quite common with non-functional requirements.

• Best practices: each programming language has its quirks, so we look for adherence to the idiomatic code. Static analysis tool can help here.

• Knowledge transfer: everybody learns. Senior or junior, we make mistakes and write beautiful code!

General aspects

Leading a code review session requires a few things to keep in mind in order to avoid biases and preconceived ideas. A session usually takes many minutes of interactions through code acceptance.

Code reviews are independent of programming languages. Scripts, build and automation code can also be reviewed. Recently, I also recommended my peers to review infrastructure code, an area whose is known to neglect code before the DevOps culture appeared. Things are changing and for the best!

The code review is only possible because of the VCS software like git. There are services that integrate with git and make it possible to have a centralized place, where you and your team members can establish a conversation and give feedback. Services like GitLab, GitHub and BitBucket are examples of that.

How it happens

This is a way to review code, with your team you should define what is best and adapt if something doesn’t work.

Developers are responsible for frequently committing their code and when it’s ready or even when they feel feedback is needed, it is a good time to start a code review. If you’re on GitLab, reviews are called Merge Request. If it’s GitHub - Pull Request.

There are different ways of starting a review according to the git flow of your choice. My team currently works with a master branch - a known place for stable code. In this case, everything we develop must pass the review before being added back to master.

After three days, you finished your so expected feature. Tests are all green, static analysis ran, no issues found. You’re ready to start a review before finally shipping your code.

It’s time to choose one or more members of your team to subscribe to the review, give suggestions and receive notifications of interactions.

Best practices

No matter if you’re opening a review or you’ll act as a reviewer, empathy must guide both of them. Respect, help and contribute with your peers. It’s a rule good manner.

As the author

Having your code reviewed demands empathy overall. Don’t try to look so smart. Let’s see a few practices that guide your good code:

• Small commits: try to reduce the number of commits. Git squash may help!

• Descriptive review: write a near-perfect title for it, with a detailed description (Is it a bug? A feature? Dark details, etc)

• Scope: keep the scope of your changes limited. Your peers will thank you.

• Explain your decisions: if there’s something a bit more complicated, algorithms choice, explain it.

• Choose the reviewers: sometimes, people are very busy, so choose wisely who can collaborate more with your review. Be by subject expertise or availability, don’t choose just your friends.

• Don’t take it too personally. Don’t be offended you received constructive critics.

As a reviewer

There are different things to look for while reviewing. I really enjoy the design aspects of the code. If we are in review session of Go code, I’ll look for the lack of idiomatic Go. Now, let’s see how to lead the review by the reviewer’s perspective:

• Purpose: does the author followed the best practices, tested and write good documentation? Does this review follow the guidelines your team established?

• Ask: this is very important. If you see code that’s is confusing, hard to understand, non-idiomatic, please ask! You’re helping not only yourself but your coworker.

• Non-function requirements: if there’s something that smells bad, ask! Let’s suppose you found a piece of good that could cause bad performance, leave a question. You may not see something your co-worker wrote or it’s justified.

• Look for unnecessary code: developers enjoy writing code, even when it’s not necessary. If you found something a lib solves better or it’s faulty, ask, suggest.

• Is this code extensible? If not, give ideas on how to make it extensible.

• Is this code clear enough for all the team members understand?

• Does this code leave a future change? The infamous technical debts. If yes, create an issue and add a due date to it.

• Are the unit/integration tests given the same care as the code itself? Test code is code.

• Security: it goes deeper, look for potential security breaches and raise questions.

• For bigger reviews (too many files, classes/methods, functions, etc), I highly recommend to checkout the branch locally and use your editor/ide to navigate the code. If you use a static analysis tool, it’ll help by warning about problems.

Biases

I’ve worked in places where people were code review fanatics. It was bad. No good conversations, just nitty pick details and a lot of egos. Please, don’t do that! I believe in teaching, educating people and feedback is priceless in this case. Why, instead of pointing your finger, don’t you show how and why your suggestions would be better?

Conclusion

Code review is an essential practice for professionals. It dramatically improves the quality of the code, decreases the number of bugs and shares knowledge. The adoption of reviewing code is part of a transition from Software Development to Software Engineering. It’s when you learn to work on a team, divide work and iterate into small steps to delivery well-engineered code.

It’s time well spent. Apparently, it isn’t generating value, but if you look closer, all your users want is software that works. It’s only possible with good practices of real engineering.

Thanks for reading!