Title: Professionalism in programming Part 4

How do you learn to be a good carpenter? You become an apprentice to someone. You watch how they ply their trade, and listen to their advice as they watch you work. You do not jump in feet first without any practical ability and expect to be able to churn out quality furniture straight away. We do not have an analogue of that in the coding world, even though it is about as much a craft as it is an engineering discipline.

Code reviews, however, do give us a little bit of that in the discipline of an engineering process. I hope that does not put you off - really!

Performing code reviews in a software company is similar in some ways to the model of open source software development. By performing reviews, you encourage responsibility for what you are coding. When you know that your code is not just for you to look at, but it will be viewed, used, maintained and criticised by others your approach tends to change. It prevents you making that 'quick change that you'll fix later' that in your heart you know you will never have time to come back to. The accountability brought on by code review brings a higher quality to coding.

Code reviews are used in traditional software engineering models. They are arguably less important when pair programming, or more than one person is responsible for parts of the code. Nonetheless, they are still useful in these situations.

As C/C++/Java programmers, we write code. At the lowest level, we are merely writing declarations, definitions and statements. From these syntactic constructs, we form some kind of semantics in each block of code. At some higher level, we have implemented a particular design by expressing it in this code.

The code review seeks to analyse the section of written code at several levels - the actual design, the expression of that design in the code, and even each individual statement to ensure its correctness. The aim of this analysis is to improve the code, largely by finding and removing faults.

According to Humphrey, "Students and engineers typically inject 1 to 3 defects per hour during design and 5 to 8 defects when writing code. They only remove about 2 to 4 defects per hour in testing but find 6 to 12 per hour during code review" [PSP]. Code reviews are a worthwhile activity!

A code review should not take the place of the code's functional specification review. The code is checked to conform to its functional specification, but the content of the functional specification is taken to be correct. If it were not then the task would be Herculean!

We need to be confident about the quality of our programming, and need to find faults as early as possible in the development process. The earlier we try to find problems, the more we are likely to find and fix.

So we perform code reviews to improve code quality. This includes:

In doing this we also check the code against a number of yardsticks, which may include:

Apart from the obvious benefits that come out of this there are other useful side-effects of code reviews. The cross fertilisation that comes from getting programmers to look at each other's code ensures that the coding style is more uniform across the whole company. It also spreads knowledge about the workings of particular bits of code, so there is less risk of loosing information when people leave.

Many people shy away from a code review for fear it will expose their inadequacies. We should not do this. Having your code reviewed is a good way to learn new techniques. You must be humble enough to admit that you are not perfect and willing to accept criticism from others. A programmer's coding style will improve as they learn from the changes made to their work.

This also means that when criticising code in a review, we must be sensitive. It is interesting that even the least experienced programmer will usually have something worth mentioning in a code review. Moreover, just as the author learns from the review, so may a reviewer.

In the ideal world every bit of code written is reviewed carefully prior to release. According to the Software Engineering Institute at the Carneige Mellon University, a thorough code review should take at least 50% or more of coding time [SQP] (although they do include 'personal' code review in this statistic).

If we do not have time to review every bit of code, how do we decide whether to review and what bits of code to review? To put is bluntly, you would be stupid not to perform code reviews at all^[2]. Compare it with product testing. You would be stupid not to test a product prior to release. The code review tends to weed out redundancy and bad design more than incorrect behaviour, but certain inexplicable 'features' would be weeded out at this stage which would be practically impossible do diagnose from a system usability test.

Often you will hear people say 'but the code's too large to review fully' or 'it's too complex, no one person could ever understand it'. If a company can employ enough people to write a large program, they can employ enough people to review it. If the code is too complex, it desperately needs reviewing! In fact, it probably needs something a little more drastic. Well-written code should be easily decomposed into sections that can undergo separate reviews.

In code reviews, we look at code under the microscope - really aiming to criticise^[3] it. This is not to get at the programmer but to improve the quality of the product/software the company produces. Having a code review is not enough. In itself, it is not going to solve all the problems. You also need to make sure that you review properly.

A code review is a formal meeting. There should be a fixed agenda (to ensure no action is forgotten) and a defined ending (not a time limit, as such, but a definition of exactly what bits of code you are reviewing, and which bits you are not - it is very easy to be woolly about this).

An example of a procedure for how to conduct a code review is described below.

There are a number of different tools that may be useful when performing a code review. For example, there are tools like the McCabe toolset [McCabe] that help trace flows of execution, and calculate values for function 'complexity'. This last metric is very useful when identifying which pieces of code need reviewing as soon as possible. A visual design program may aid in understanding the code structure and its dependencies (particularly in object oriented languages like C++ and Java).

Code reviews are an essential part of the software development process. Just as an apprentice learns their trade from knowledge passed on, code reviews spread knowledge and teach coding capability. As more of a peer-to-peer than master-apprentice activity, they provide a learning opportunity for author and reviewer alike, and result in higher quality code.

In the light of code reviews, you should write your code bearing in mind that it is not just for you to read. Other people must be able to maintain it as well. Authors are accountable for the quality of their code.