Code Review — Helping Developers to Help Themselves

Code Review, (sometimes referred to as Peer Review) is a software quality assurance activity in which one or several people check a program mainly by viewing and reading parts of its source code after implementation or as an interruption of implementation. At least one of the persons must not be the code’s author. (Baum, Tobias; Liskin, Olga; Niklas, Kai; Schneider, Kurt (2016)).

If you do not perform Code Reviews at your project's source code, stop right there!

The Code Review is, in a software project, as indispensable as writing the code itself. If you do not consider it part of the development process, probably you will think it is a waste of time and you might ask yourself: "why should I bother reading someone else's code every time a new pull request is opened? Isn't the fact that the application is working enough?"

Let me tell you a short story: code is written by humans. Humans make mistakes, therefore, code has errors. Simple as that!

Here are some tips to help you improve the quality of your code reviews. I've written examples in JavaScript but the concepts may be applied in whatever language you use.

Nomenclature of Variables

Within a software source code context, variables are key for its understanding. Have said that the clearer most adequate their names are considering what their values represent, the easier the implemented routines understanding becomes. Avoid using initials. It might be clear to you who is the author of the code but it will not for those that need to maintain that code later. Setting standards for the variables' names help the team to create new code in the same way, speeding the code review process and maintenance. These are some questions you can ask yourself in regards to the variables names:

  • do the variables have a meaningful name?
  • are the case patterns being followed? (PascalCase, camelCase, etc.)
  • is the code following the adopted methodology? (BEM, OOCSS, etc.)

Unused Variables or Methods

Besides increasing memory allocation unnecessarily, unused variables and methods harm the understanding of certain components or routines and confuse code reviewers. Make sure that there are no unused references inside your code. Make friendship with code linters. They will help you a lot!

Inline Assertions x Computed Variables

Inline assertions are not always easily understood. So, creating variables and naming them meaningfully makes the code more readable and eases the understanding of the implemented logic. Take a look at this example:

Code Structure

People are different, therefore they write different code. When more than one developer is working on the same project, it’s normal to have similar routines written in completely different ways. A company or a team needs to determine certain standards that must be followed by everyone.

By doing a Code Review the team can easily look for and point structures, approaches, or techniques that defer from the company style guide. This will keep the code homogeneous facilitating the reading, analysis, organization, and maintenance of the source code.

Single Responsibility Principle

If a function is quite long, probably it is doing more than it should. This goes against the Single Responsibility Principle (the S(RP) from SOLID). "What does everything, does nothing at all" (Myself).

Look for extensive components, functions, or routines and try to identify if they can be split into smaller and more specialized artifacts. This will lead to a more maintainable and testable code. Remember: a function must be responsible for only one thing and must do it well.

Negative Conditionals

Usually, negative conditions are harder to read and assimilate at first glance and may lead to confusion, mainly within a more complex logic. So, if you find negative conditionals suggest the author replacing them with negative variables. Keep in mind that it is always easier to read code without the negative sign in front of it. Example:

Overtesting

Look for unnecessary tests. A nice approach is to implement unit tests that really reflect the business logic. If a function is made of several others, why create several tests for all of the small ones if creating just one or two tests for the main one might be enough to check for real case scenarios?

Of course, if a function is used in more than one place for different purposes, it will probably make sense for you to test it separately.

Remember that, testing small functions will produce a bigger amount of tests and they tend to have simple inputs while testing a more complex function, which calls other routines, might produce fewer tests but with more complex inputs.

Functions Nomenclature

Analyze how methods and functions are being named. We all know that functions really do things. So, why not make it clear to other developers that might need to read the code?

So, check if their names always start with a verb, which represents an action, except for functions that return boolean results, these might be named following the question/assertion structure. Examples:

Avoid subjective names like process(), run(), do(), execute(). When this approach is needed, consider the name of the variables passed as a parameter to enrich the meaning of the functions. Using currying might help a lot with this. Examples:

Conclusion

All of these tips are not the absolute truth in terms of Code Review or good practices in software development, but they might help you become more assertive and have the right arguments to ask for fixes after checking someone else’s code.

Some of them come from the Clean Code philosophy and others from my personal experience. The fact is, whether you implement them or not, do a favor to your team, company, and yourself: perform code reviews! Do not take code for granted.

A slightly different Portuguese version of this article can be found on LinkedIn.

--

--

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store