Do you proofread your code?

Cartoon making fun of people who don't proofread.

Image taken from

When I write a blog post, such as this one, there are a few steps I follow before committing any new entry to the world:

  1. I type a first draft out in Google Docs.
  2. When I'm reasonably happy with the post, I type-set the post in HTML.
  3. I then proofread the post and fix any mistakes.
  4. I put a copy of post up on the site but it is not linked from anywhere on the main site.
  5. I then proof read again and fix any mistakes. This is the last chance to get it right and I usually leave it a day or so before doing this final proofread.
  6. I make the blog post available to the world.

The process is not perfect. I'm sure there are many errors that survive right in to the final blog post. The fact that these errors survive is sort of beside the point. The point is that this process dramatically improves the quality of this blog.

I was told by my English teacher when I first started writing essays back in my high school days that I must proof read my work before I submit it. She said, "Proofreading your essay will save you time because you'll fix a lot of the mistakes before I find them. If you don't proofread your work then your essay will come back to you covered in red ink and you will probably have forgotten what you'd written. As such, it'll take you much longer to fix the mistakes."

Doesn't that sound like everything we know about software defects?

And then it struck me. While I automatically proof anything I write on the web, how often do I proofread my code? In all honesty, I've never done it seriously. I've never taken a check-in I've made, printed it out, then sat down, worked out what each routine was meant to do, then come up with a proof as to why the code really does do its job properly. How often does anybody really proof read their code like that? In my entire (and fairly short) career, I've never seen anyone do it.

Moreover, how many people give that print-out to a colleague to examine? I'd bet that very, very few organisations do that. How many people sit around a table and proofread their code together? I guess it'd be even fewer.

With that in mind, is it any surprise that before we subject our code to testing there are typically eighty defects per thousand statements in our code?

Could you imagine an author publishing a book without proofreading it at least once? Could you imagine an author publishing a book without giving the manuscript to someone else to look over? Why is it acceptable to publish software without doing even this basic level of quality assurance?

Then I had another epiphany! This is why formal inspections remove up to 90% of the defects before the first test case is run. It's not that having inspections really finds the tough, race-condition style, kinds of bugs. Most of the time, they find trivial problems.

Think of if it like you're using a word processor to write an essay: If compilation finds the "spelling" mistakes in code, formal inspections find the "grammatical" mistakes. You're not finding the deep errors in your program, you're just finding the next layer of superficial defects. Yet these sorts of defects make up almost all of your bugs.

Proofreading in a small group is the closest thing we have to break-through technology in defect reduction. Robert Glass had this to say about formal inspections:

Rigorous inspections - the technique of pouring over a piece of software to identify any errors it contains - constitute a near-breakthrough. Research study after research study has shown that inspections can detect up to 90 percent of the errors in a software product before any test cases have been run. And that signifies an extremely effective process.

Furthermore, the same studies show the cost of inspections is less than the cost of testing that would be necessary to find the same errors. What we have here is an effective process that is also cost-effective.

According to the research, the key to successfully finding errors is to be as rigorous as possible in your proofreading. Do not mistake rigour for formality. It is entirely possible to do a formal inspection but be intellectually lazy about it. Any such approach is doomed to fail. Rigour means that you need to sit down and really concentrate hard on the code in question and not just go through the motions of a formal process.

If this sounds like hard work, it is. According to Glass it is not uncommon to only be able to inspect a hundred lines of code per hour. Worse, the process of going through the code so rigorously is mentally exhausting. An hour is the maximum that most people can do at a time.

But it's worth doing. The research does show that those who dare, win. If you're willing to do that punishing work, you'll be able to develop quality software much cheaper than your competitors.

Without a proofreading programme, when a bug is fixed by a tester the bug is usually fixed leaving the design of the program entirely unchanged. By having a solid culture of peer review, it's much more likely you'll fix bad design decisions as well as the bugs. This means that your code base will probably be smaller, more efficient as well as being much less bug ridden.

If you're still not convinced, take this passage from Steve McConnell's Code Complete:

The combination of design and code inspections catch about 60 percent of defects, which is higher than other techniques except prototyping and high-volume beta testing. The results have been confirmed numerous times at various organisations, including Harris BCSD, National Software Quality Experiment, Software Engineering Institute, Hewlett Packard and so on.

The combination of design and code inspections usually removes 70-85 percent or more of the defects in a product. Inspections identify error-prone classes early, and Caper Jones reports that they result in 20-30 percent fewer defects per 1000 lines of code than less formal review practices.

Designers and coders learn to improve their work through participating in inspections, and inspections increase productivity by about 20 percent. On a project that uses inspections for design and code, the inspections will take up about 10-15 percent of project budget and will typically reduce overall project cost.

Just like an author subjecting their manuscript to review makes their book better and improves their ability to write, having others review your code makes your code better and it helps makes you a better programmer. Not only that, it makes you 20% more productive!

So perhaps a good New Year's resolution for any developer would be to set-up a proofreading programme at their company!

2009-01-11 16:20:40 GMT | #Programming | Permalink
XML View Previous Posts