The Best Code Review Tool is a Simple Ball Pen and a Listing on Paper!

BY MARKUS SPRUNCK

The continuously increasing need for more and more speed in software development fosters the use of static and dynamic code analysis tools.

Code analysis tools are great, but don't think that static and dynamic code analysis tools can substitute the old fashioned peer review between humans.

When we talk about code reviews we can find three fundamentally different types of code reviews:

  • automated tool based reviews with code analysis tools,

  • software inspections and

  • lightweight code reviews.

My personal favorite is - as you may see in the title of this article - the more informal 'lightweight code reviews', but also tool based analysis and formal software inspections are useful in the right context.

Don't get me wrong I believe in numbers and tools, but automated code review tools will never replace peer reviews between humans, because code reviews have two complete different benefits:

  • The first is to find defects in an early project phase and here automated tools really help to reduce the difficult and slow review of source code. This may be done with tools like Findbugs, PMD, Checkstyle, and many more. See also 'List of tools for static code analysis' [1].

  • The second benefit is the know-how transfer and/or alignment between humans. Especially the informal reviews foster the dialog between developers and help to get better. This aspect can't be done with tools and is very important to improve the skill within teams.

In the following, the three main types of review will be discussed in more detail.

Software Inspections

The key ideas of software inspections are more than 35 years old and in some settings still very useful. Sometimes the inspections are also called 'Fagan Inspections' - 1976 M.E. Fagan published an ground breaking article "Design and Code inspections to reduce errors in program development" [2]. Software Inspections are extremely formal with defined rolls, activities, checklists, and templates. [3]

The big advantage is that you find more findings in predefined fields than in simple lightweight code reviews. On the other hand, the effort is large and makes just sense in projects with strong requirements of quality. Therefore inspections can mainly be seen in the defence industry, aviation and medical fields.

Some years ago I have been involved in the introduction of typical Fagan Inspection in a large IT organisation. It was a disaster, because it was just to much for the beginning. My estimation is that about 10% of the teams had no problem with the new process, but the rest was either convinced that there is no benefit at all or it is to time consuming. The interesting aspect is that the teams with no or less problems have had - in most of the cases - already experiences with informal lightweight code reviews.

Automated tool based reviews with code analysis tools

There are two categories of tools static code analysis tools and support tools to document and manage reviews.

Static Code Analysis Tools

Static code analysis is an absolute must for every software development team! There are a lot of tools with different strengths and weaknesses available. Most of the tools work with the source code and some with binary code. E.g. in Java development the following tools are very helpful:

  • Findbugs - finds bug pattern in binary code and focus on typical errors [4],

  • PMD - reports also bug pattern and best practises in the source code [5] and

  • Checkstyle - is specializes to coding conventions [6].

The use of these tools on an daily base is strongly recommended and works best in combination with Sonar [7]. It uses - besides others tools - Findbugs, PMD and Checkstyle for analysis. One big advantage is the Eclipse plugin which fetches the centrally managed rule set from the Sonar server and provides in this way a simple unified interface to the developer.

Support Tools to Document and Manage Reviews

My personal opinion is that the use of the first category 'static code analysis' is a absolutely must in every development and/or maintenance team. This is increasingly popular, but at second glance it is more a task management of warnings from the static code analysis tools.

Lightweight code reviews

As the title implies this type of code review is my favorite n most development activities. Lightweight code reviews are easy to introduce and give more freedom to exchange know-how between two or more developers.

Figure 1: Peer review protocol with hand written comments

This it the best way to start with reviews in a team. The best is to print out the source code to be reviewed and take a ball pen to mark all findings during the peer review on paper. Reviews on paper have the big advantage that you can focus on the code and avoid all overhead like in Fagan Inspections. Usually the acceptance from developers is good and you can still document the reviews and fixing of found defects.

Recommendations

  • Always use static code analysis to find and fix the low hanging fruit and avoid the simple defects to come into the peer reviews. You know the rule "shit in shit out" and this is especially true for peer reviews.

  • Don't use a tool for managing code reviews if know-how transfer is Important. Just start with lightweight code reviews on paper with ball pen.

References