Putting It All Together: Code Reviews

All previous sections in this chapter lead to the code review. Each section reinforces the others and paves the way for meaningful collaboration in the form of code reviews.

Authors have editors, builders have inspections, and judges have appellate courts; even cosmetologists have oversight. Programmers, on the other hand, have none of these things. Although bad code often has serious real-life consequences (such as grounded planes or stolen identities), we don’t handle formal reviews very well as an industry. Healthy code needs accountability, and that requires many sets of eyes on the same code. Here’s the thing about code reviews, though: good code reviews take effort, and inconsistent code provides friction that multiplies that effort.

Automating Your Consistency Checks

Everything we’ve written so far builds up to writing the healthiest, most consistent code possible so your reviews can be better and more effective. You don’t have to follow all of these techniques, but each one helps prepare a pull request so the reviewer can focus on what’s important to you. Putting together the last few sections we can now create an alias in your mix.exs to do all the work for us. You can make your mix file look like this:

Now, whenever you run this alias, you’ll get all the information a developer needs—from style to documentation to typespecs and test and test coverage—before a code review, after a major refactoring, when hiring a new developer, or before a major release. When these requirements are met, you’ll be better prepared for whatever the world throws at you.

You may even decide to run tests, or check for the existence of one or more of these artifacts each time you commit. To do so, you can use a continuous integration (CI) server such as Travis-CI,^[26] circle-ci,^[27] or Jenkins.^[28] Another compelling tool is Ebert.^[29] This tool automates your review process by running linters such as Credo each time you do a pull request. In the interest of full disclosure, keep in mind that Ebert is a paid service from Plataformatec, the company behind Elixir.

The computer can do the things computers are good at—measuring test coverage, enforcing types, and the tedious job of implementing consistent style. The computer can even automate enforcement of the above. Reviewers can then focus on ensuring that business logic matches your business rules, and the functions do what they are supposed to do. Let’s assume you’ve run your consistency check, with a CI server or by hand. The next step is to get a set of experienced eyes on that code.

Performing Code Reviews

The best way for new programmers to learn is to start coding—but that’s not enough. Coders need oversight just like code does. Without good mentoring and proper reviews, simply writing code just reinforces bad habits. Good mentoring that can augment code reviews instead breaks bad habits before they start and reinforces good behaviors.

How you do code reviews is up to you. Sometimes, two developers can pair, with the author walking the reviewer through the most critical details. Other times, team leads might review code from a formal pull request, or a senior developer might simply read through a commit summary. You can use many different approaches to get to the same place. The important thing is that your development process builds in accountability and oversight so real people read code as soon as it is ready. Keep these concepts in mind as you decide what’s best for you:

• Larger and more inexperienced teams need more communication.

• Larger teams need more formal mechanisms to enforce reviews.

• Reviews are one of the most important ways to ramp up inexperienced developers quickly.

• All teams need regular reviews.

Once you’ve decided how to perform your reviews, your next decision is how to provide feedback. A quick word of advice: code reviews don’t impact all programmers in the same way. Stay gentle and kind. Refrain from making judgments about people, and avoid biting humor. In this context, such comments often prove more toxic than you expect.

Even if your reviews are verbal, it’s best to come out of each review with a tangible punch list. Your punch list may be an informal text file, but tickets work best. You can even combine many tasks in a single ticket if the requests aren’t too sweeping. This approach allows you to formalize follow-up with the tools you already have on hand.