Title: Outsource Your Self-Discipline

Author: Martin Moene

Date: 03 October 2011 09:44:55 +01:00 or Mon, 03 October 2011 09:44:55 +01:00

Summary: Itâ€™s all too easy to skip those tedious but vital steps towards code quality. Filip van Laenen suggests getting someone else to do them.

Body:

Huge progress has been made in the past decade in the field of code quality assurance. Test-Driven Development (TDD) and Pair Programming are two key practices that have made a big difference and improved code quality substantially. Many readers will agree however, that thereâ€™s still plenty of room for improvement. One important factor is that the IT systems that we build today are among the most complicated systems mankind has ever made. On the other hand, many of the tasks related to code quality are simple yet very repetitive, and therefore also extremely boring. As a consequence, doing the simple tasks like good and consistent code formatting, or proper function and variable naming, are usually more a question of conscience and self-discipline than knowledge and training. Is there an alternative to all the things we let slip due to bad conscience on a daily basis in our industry?

Why would you need assistance?

Even though there are many good arguments for pair programming, one of them is in my opinion wrong even though it is a very popular one: the idea that the second person will act to keep you on the straight-and-narrow. However, using a colleague to watch over your shoulder so that you give your functions appropriate names, that you comment your code where itâ€™s necessary, or that you donâ€™t write deeply nested functions, is a waste of resources we really canâ€™t afford in our industry. If you donâ€™t bother doing it when youâ€™re on your own then why do you punish your colleague with this boring task? Besides, you have a friend whoâ€™s much better at it. In fact, heâ€™s much faster, does the job better and in a more consistent and precise manner than any of your colleagues, and he never gets tired of boring, repetitive, trivial jobs. Thatâ€™s right, Iâ€™m talking about your computer. Just think of how many lines of code it can analyse in a millisecond and compare it to how much time your colleague will need just to check that a single line of code is formatted correctly.

But even if youâ€™re a disciplined programmer who always formats his code consistently and practises TDD according to the book, your computer can be of great help. Remember the principles of TDD? The flowchart in Figure 1 gives a quick overview: first you write a failing unit test, then you write only as much source code as needed to make the test pass. Next you refactor the code if needed, and unless youâ€™re done, go back to the start and write a new failing unit test. But how do you know whether you should refactor your code or not, and how do you know when youâ€™ve refactored it enough? Everybody has an idea about what â€˜good codeâ€™ looks like but itâ€™s often a very subjective thing. What looks â€˜good enoughâ€™ today may look â€˜just below the barâ€™ on another day. And once youâ€™ve started refactoring it may be hard to stop when itâ€™s just â€˜good enoughâ€™ and instead continue to polish the code that little bit more.

Figure 1

Just to give an example: unless youâ€™re using a programming language in which calls to subroutines are very expensive, having fifteen levels of nesting in a single method is definitely a sign of bad code quality. But if you start refactoring the method how do you know when you should stop? Reducing the nesting to six or seven levels clearly isnâ€™t â€˜good enoughâ€™, but what about three or four levels? And is three levels â€˜good enoughâ€™ so that you can move on to the next problem, or should you continue until all functions have no more than one level of nesting?

Whatâ€™s even more difficult is getting four, five or even more programmers to agree on what will be the minimal code quality requirements for a project. And thatâ€™s before you want them to apply those minimal requirements to every piece of code in the project in a consistent way and without long (or even endless) discussions, throughout the lifetime of that project. Wouldnâ€™t it be great to get help from an impartial judge, who can give his opinion about the quality of a certain piece of code based on a set of objective criteria? Again, this is where the computer can help you, e.g. applying some automated rules against your code in order to check that it meets the minimal code quality requirements you all agreed upon.

How your computer can help

There are many tools available that you can use to check the quality of your code. Some of them can be plugged into the build process so that all developers in your project team can follow the exact same coding standard, and that all code adheres to the same minimum code quality requirements. Youâ€™ll get the best results if you let the build process fail whenever violations are found, but thatâ€™s not always possible, or it may not fit with your organization or the project youâ€™re working on right now. But in my experience when you use the tools to only generate reports, nobody will read the reports, let alone act on them to clean up the code.

So what are the tools that we can use to improve code quality? Automatic code formatting, static code analysis, test coverage reports and mutation testing are four examples of tools that can take care of some of our self-discipline. Letâ€™s have closer look at each of these tools, to see how they work and what they can do for us.

Automatic code formatting makes sure that all code conforms to the same coding standard all the time. Sure enough, these tools arenâ€™t able to format all code exactly the way you wish, but on the other hand they never forget to format it, theyâ€™re never sloppy, and they never change their mind. That is unless you change the code formatting rules, but if you ever do that the tool will reformat all the code according to those new rules instantly. Many people are sceptical about automated code formatting tools, but I still think itâ€™s better to have 100% of the code formatted in a consistent way all the time than to have 10% inconsistently formatted because a tool would not be able to format the last 0.1% of the lines exactly to your taste.

Most modern IDEs have some sort of code formatting tool included, but itâ€™s often possible to do better than that. Indeed, one of the problems is that if you want to use an IDEâ€™s code formatting tool in your project youâ€™re still relying on your developers manually running the formatting tool against every code file theyâ€™ve modified before they check in. Furthermore, making sure every developer in your project uses the same code formatting rules can be a challenge too if it canâ€™t be distributed easily and used by the IDE automatically.

In my experience you get the best results if you can run the code formatting tool completely automatically, virtually outside the control of the developers. Maybe it can be part of the building process, e.g. using the Jalopy-plugin to Maven in a Java project [Jalopy]. Alternatively you may be able to fire the code formatting tool from a hook of your version control system, e.g. upon check-in of code files. But if neither of them is possible in your project, you may resort to using tools like Checkstyle [Checkstyle] to check whether the code conforms to all (or at least some) of your code formatting rules. And if even thatâ€™s not possible you can always run grep, e.g. using a regular expression like \{\s*\} to find empty blocks in curly-braced languages.

Static code analysis can be used to find undesired patterns in your code. These patterns range from simple things like empty blocks and writing to the console over deeply nested functions, confusing or overly complex code to known â€˜anti-patternsâ€™, and potential bugs. Notice that many compilers have options to enable some static code analysis, usually in the form of warnings, but dedicated tools have a wider range of rules and patterns they can check. If you want to apply static code analysis on an existing project, start with a small rule set and pick from time to time a new rule that looks useful for you. Remove all violations of the rule from your project, one at a time. Then, when youâ€™re done, consolidate the rule by including it in your rule set so that you (or your colleagues) wonâ€™t create new violations of it. When you get the hang of it and youâ€™ve implemented most of the rules that looked useful to you, maybe you should consider creating your own rules to get rid of some of those particular bad habits you or your colleagues have. And if youâ€™re using an open source tool, maybe you even want to donate them back to the project so that others can benefit from them too.

Thereâ€™s a large variety of tools that can be used to analyse your code statically. In fact, compilers often have some options you can switch on to do some very basic static code analysis. The already mentioned Checkstyle focuses mostly on coding style but it also does some static code analysis. FindBugs [FindBugs] and PMD [PMD] are two other tools for the Java language, the former being a bit more oriented towards finding bugs per se whereas the latter casts its net more broadly. If youâ€™re a .Net programmer you should probably check out FxCop [FxCop]. Lint is the original static code analysis tool for C, and Cppcheck [Cppcheck] is probably the de facto standard static code analysis tool for C/C++. If you program in another language, or you want to check out even more static code analysis tools, be sure to check out Wikipediaâ€™s overview [Wikipedia].

It should be noted that static code analysis on dynamically typed languages is a difficult task. In fact, one could almost say thatâ€™s so by definition if you notice the â€˜staticâ€™ on the one side and the â€˜dynamicâ€™ on the other. Nevertheless, even for a language like Ruby there are some tools available, e.g. Roodi [Roodi]. Itâ€™s even possible to create your own static code analysis tools using, amongst others, regular expressions and string functions. A few years ago, I was on a project where we had a simple tool making sure all SQL scripts followed some basic rules.

Test coverage tools will reveal which parts of your code arenâ€™t tested by your automatic tests, or maybe even not in use at all. Sometimes low test coverage isnâ€™t an issue, e.g. when itâ€™s difficult to set up automatic tests against a simple and stable interface thatâ€™s easy to test manually. But the core of your system, the part where most of your business logic resides, should have a test coverage rate as close as possible to 100%. Aim for the high numbers in those parts of your system, not just 60% or 70%. If you canâ€™t reach your goal, try again before you lower your goal or make a local exception. And donâ€™t forget to consider deleting some code â€“ youâ€™ll be surprised how often thatâ€™s the right decision.

In this category too there are many tools available to help you in your project. I have used both EMMA [EMMA] and Cobertura [Cobertura] in Java projects with great success, and Rcov [Rcov] in some Ruby projects. If youâ€™re a .Net programmer, NCover [NCover] is probably the tool for you, but there are many others. Just as for static code analysis tools, Wikipedia has a page [Wikipedia2] with a good overview of tools available in a number of programming languages.

Mutation testing is a very powerful tool, but sometimes can be a bit annoying and irritating. It can be described as a sort of automated code critique, and in the beginning it can be hard to accept the results it produces. What it does is that it makes simple changes (â€˜mutationsâ€™) to the source code that are guaranteed to change the behaviour of the system. Switching a condition or removing a line of code are good examples of changes that should be noticed somewhere. When it has made a mutation, the tool checks that at least one unit test starts to fail. If no test fails clearly something is wrong. Maybe the tool found a condition that isnâ€™t covered by a unit test, and you should add one? Or maybe it found a branch that canâ€™t be reached and you can delete some code? I have to confess that, even though I have used it for years, there are still occasions where I have to manually apply the mutation to the code and run the unit tests again, just to accept that what it says is correct. On the other hand Iâ€™ve learned a lot from it, even though it can sometimes be very irritating that it so meticulously points out the mistakes I make in unexpected places.

Personally, I havenâ€™t had much success yet running mutation testing in any language other than Ruby. There may be something particular about Ruby that makes it well suited to mutation testing, or it could be that the programmers behind Heckle [Heckle] found a clever way to make the set-up of the mutation testing easy. I would like to mention Jester [Jester], Jumble [Jumble] and PIT [PIT] as three mutation testing tools for the Java language that look promising, but so far donâ€™t seem to be quite mature yet. I hope to see some evolution here, because mutation testing is one of the things I really miss when programming in Java.

Figure 2 explains how the code quality tools discussed fit in with TDD. Automatic code formatting doesnâ€™t appear in the figure because it happens behind the scenes and is therefore totally transparent to whichever development method you use otherwise. Static code analysis, code coverage and mutation testing are part of the decision box in the middle and help to find an answer to the question of whether the code quality is good enough. Note that code coverage reports and mutation testing often will give you the inspiration, even if they donâ€™t actively force you, to write new unit tests, and therefore in a sense can send you straight back to the â€˜Write or modify a testâ€™ box.

Figure 2

Getting started

If you want to use any of these tools, introduce them slowly in your project. Itâ€™s always a good idea to start with the generation of some reports just to see how youâ€™re doing. Then try to fix the simple things, and start automating your code quality requirements. As you continue to use the tools and add more and more requirements, youâ€™ll learn how the tools work, and you can start to create your own rules or extensions. But donâ€™t add requirements you donâ€™t understand, and maybe even more important, how violations should be fixed, because that will bring you problems. Over time, youâ€™ll see that old problems and bad habits that have plagued your project over a long time, will disappear, and never come back.

Itâ€™s important, however, to understand that these tools wonâ€™t solve all your code quality issues. You and your colleagues will still have to use your brains while youâ€™re programming, because not all software quality requirements can be expressed in rules that can be automated. But these tools can automate some of the most boring tasks, so that you can concentrate more on the creative, fun part of programming. And isnâ€™t that why we all started programming in the first place?