Every developer knows the pain of banal mistakes. A wrong attribute here, a misspelled property there, an accidentally duplicated line of code which you missed because of the coffee-fueled 16 hour hackathon you’ve been on. Even a simple $ before the opening PHP tag which you accidentally put there because you started typing before the infernal Java-based IDE warmed up and re-positioned the cursor can leave you scratching your head for hours on end if you’re tired and distracted. If only you had a fresh pair of eyes to look at what you did – surely these mistakes could easily be avoided?
Wikipedia defines code review as follows:
Code review is systematic examination (often known as peer review) of computer source code. It is intended to find and fix mistakes overlooked in the initial development phase, improving both the overall quality of software and the developers’ skills. Reviews are done in various forms such as pair programming, informal walkthroughs, and formal inspections.
This definition is as precise as it gets – in even more layman terms, code review is simply the act of having someone else look at your code to find the mistakes you missed.
The Types of Code Review
As the Wikipedia definition hints at, there are many different ways to review code for defects. Here’s a quick break-down of a few of them:
- OTS (Over the Shoulder) Review – This is how small teams usually handle code reviews. A developer will write a decent amount of code and call another developer over to have a look at it. The other developer sits there while the first one explains what he did, line by line. Through this narrative, the original developer notices some of his own mistakes and fixes them, and the OTS developer notices others, pointing them out to the first. They also share opinions on solutions to certain problems which the original developer will sometimes redo after the review process is done, calling for a review once again. This can also be easily done with screen sharing software and voice chat if the developers are remote.
- Tool-Assisted Review – there are various tools both online and offline to assist with code review. While a detailed look at the various tools on offer is outside the scope of this article, we can generalize and say there are paid versions (Atlassian Crucible, CodeCollaborator), free versions (Review Board) or, if you’re solo developer, the community version (Stack Exchange Code Review). Regardless of the tool used, each serves pretty much the same purpose – it retrieves the most recent changes to source code and flags them as needing review. A peer – that means a developer of equal or greater skill – then reviews the code, flags it as reviewed or marks any errors that were found and makes suggestions, and either finishes or reinitiates the process by sending it back to the originating developer. It is also important to note that many popular IDEs have code review plugins.
- Pair Programming – A very dynamic type of code review, pair programming is a hotseat “game” for two developers in which one developer codes and the other follows his progress by sitting beside him. After a couple hundred lines of code or after they reach a predetermined milestone, they take a short break and switch places. The one who was coding now observes while the one who previously observed now codes. This is extremely effective in avoiding bugs and improving overall code quality, but it costs twice the manpower. Many companies are not ready for such a risk and are unfortunately unable to think in terms other than “two people on two machines do more work than two people on one machine”. It is precisely this type of review that yields the best results: not only are bugs avoided flat out, but the two developers directly collaborate and share ideas on solutions to problems they encounter as they progress. It is also worth nothing that this type of review is incredibly difficult to implement in teams that aren’t used to it – it mostly works on younger teams.
As an aside, there is also a formal type of review, first introduced and researched by Michael Fagan in the 1970s (this method is also known as Fagan Inspection), now somewhat archaic and out of favor in the industry. Formal inspection is rarely used in small teams and mostly pertains to several-million dollar products as it is very mentally intense and expensive. It includes several people (up to six) sitting down with a projector and reviewing code together. Each participant is assigned a role (such as Reader, Moderator, or Reviewer) and when the team notices bugs or defects of any kind, everything is detailed to a great extent – from severity, to the actual line of code, to the cause and effect, even the predicted cost of this bug reaching the customers. This is by far the most professional type of code review, but also the most discouraging to developers and as such not widely adopted. Studies have shown other methods of code review to be just as effective if used right, without the need to tie down that many people for so long.
Best Practices for Code Review
Once it’s been decided to implement code review, there will probably be some hurdles to overcome. Management may not see justification for the extra time review takes, or some programmers may think a review is a personal attack against the code they worked hard to create. Here’s some tips you’ll do well to keep in mind when code review is implemented.
- Know your common mistakes and actively fight them. When working, every developer has errors he commonly makes no matter how deep “in the zone” he is. Each and every one of us has this little glitch that is just silly and noticed outright by others. Take note of these slip-ups. Forgot to filter input… again? Forgot to comment a method… again? With a list like that, a developer can actively hunt down those mistakes before calling for a review. This is known as the ego effect – you know your code is about to be reviewed and you don’t want to hear the reviewer saying “Aw man, you forgot to filter input again!” You want to be the rockstar, the ninja, the person who makes others say “Wow, that’s actually a great solution”. The ego effect is what will drive you to improve your code before others even have a chance to take a look at it.
- Peer code review means being reviewed by someone of equal or greater skill. As should be common sense, code review cannot work when a junior reviews a senior’s code. The junior might notice some usual discrepancies, breaches of standard, typos, or even errors like input filtering, but will usually be unable to identify a bigger problem. This will often require the definition of a hierarchy by skill in the team if one is not already present.
- Less code with clear milestones means better reviews. Code should be reviewed only after a personal milestone has been reached, and these milestones should be small and should happen often. In object oriented programming this is especially important, but also especially doable. Finished a new component which extends an interface which ties into an adapter that’s already been reviewed? Finally fixed a problem with a specific method that’s been bugging the department for a week? Great! Component by component, and keeping it up to a maximum of 700-800 lines of code at a time (comments inclusive) is what produces the absolute most efficient review process. Keep the code you need reviewed short, concise and independent and do the review as soon as possible after finishing while the ideas are still fresh in your mind. Just remember – time is expensive, so don’t take too much of it either! An hour should be more than enough to perform this “section review”.
- Collect metrics. This is easier if you’re using a more structured type of code review like tool assisted or formal, but can be done in OTS as well. Try to note the number and types of bugs and slip-ups you find through a given number of lines of code and units of time. Aggregate this data across developers and easily find out who needs the most help, who breaches the most standards and how much money you actually saved your company by doing code review. Soon you’ll be able to actually quantify the usefulness of code review, and only then does everyone in the company become actively intrigued by it. This is usually the most difficult part of a review to implement, as few developers have the patience for manual statistics, but it can be beneficial if adopted.
- Be mindful of the social aspect – finding bugs is good, not bad! It is imperative to remember that finding bugs is good, not bad. Never stigmatize or single out a developer who made a mistake, make it informal. Have people adapt to code review – help your peers accept it, not fear it. Code Review can not only be useful – it can be fun as well. Remember that more time and more difficult tasks equal more bugs – the number of bugs does not indicate a developer’s skill! If you’re a manager or team leader, make sure no one sees code review as negative or a waste of time. Make sure they don’t see it as a rule enforced by the company but as an improvement to their everyday workflow which they should keep regardless of the company they work for. Whenever possible, strive for a personal approach of code review. If you’re using tools, use them in OTS as well. The personal approach of mutual brainstorming and informal discussion of potential solutions to problems is invaluable in the process of accepting code review as your friend.
Code review can be incredibly difficult to implement, especially in a team of old-timers who aren’t used to it. But once done, it will not only decrease the number of defects in your code, it will also increase collaboration and help team building, improve “brotherhood” amongst developers and will propagate best practices and improvement of skill across an entire team or department. Any type of code review is better than none, so if your team isn’t using it today, suggest it. It can only help. If you’re a solo developer, find a kindred spirit to review code with – go online, socialize, expand your development circles, team up. Don’t look at other developers as competition and at code review as your enemy, look at others like brothers in arms with code review as your weapon on the front lines to perfection.
Image via Fotolia
Bruno is a blockchain developer and technical educator at the Web3 Foundation, the foundation that's building the next generation of the free people's internet. He runs two newsletters you should subscribe to if you're interested in Web3.0: Dot Leap covers ecosystem and tech development of Web3, and NFT Review covers the evolution of the non-fungible token (digital collectibles) ecosystem inside this emerging new web. His current passion project is RMRK.app, the most advanced NFT system in the world, which allows NFTs to own other NFTs, NFTs to react to emotion, NFTs to be governed democratically, and NFTs to be multiple things at once.