Producing and maintaining high-quality code

Wednesday, April 26th, 2006

So much bad and ugly code is being spewed out every day all over this planet that entire websites are dedicated to the preservation of the worst specimens. In this post, I will show you simple ways to produce and maintain high-quality code because, firstly, this is one way of achieving Internet stardom that you probably want to avoid and secondly and more importantly, you know how painful it is to have to maintain bad code.

I will start by a disclaimer, using Douglas Adams words:

The problem with designing something completely foolproof is to underestimate the ingenuity of a complete fool.

You can follow all the tips in this post and still end up with bad code, but you would have to be a very crafty fool!

1. Understand the problem

If this sounds like a duh-ism, that is because it is one. If you do not understand what the code is supposed to do, you will not get it right. Before you start coding, whether you face a blank sheet or whether you are maintaining code, sit down and think: what problem am I trying to solve here.

2. Write unit-tests

I could almost have numbered it 1bis. Unit tests show and validate how the code is supposed to be used. Write the tests first if possible — unless you can get your hands on a time-machine, this is not an option when doing some maintenance. The quality of your interfaces will improve dramatically because you will design them from their user’s point of view.

3. Talk to your cardboard friend

How many times were you stuck on a problem, decided to seek help from a nearby colleague, explain the situation and bingo! the solution became obvious. Your colleague hasn’t even had time to pronounce one word, he probably didn’t even understand the question. Articulating the problem solved it. My nearby colleague calls this the “cardboard friend” because people drawn on cardboard tend to have the property of listening without interrupting.

4. Enforce a coding standard

I previously wrote about this but just in case you missed it: you need a coding standard to make your code homogeneous because reading code is hard enough, you do not need the distraction of multiple coding styles. Once you have a coding standard, use tools to enforce it. In Java, checkstyle rocks and if you use eclipse, be sure to check out this plugin. There are similar tools in most languages, use them! At first configure them to be a complete and utter pain and then relax the rules you believe are damaging.

5. Use code analysis tools

Use any tool you can find to study and analyze your code. If the language you are using is compiled, turn on all warnings on the compiler: use -Wall when you use gcc, open the preferences in Eclipse and activate most warnings for the Java compiler (be pragmatic). Use any lint-clone you can put your hands on for your language. Here are the tools I recommend for Java: JDepend to measure the quality of my abstractions and to avoid cyclical dependencies, PMD to identify potential bugs and potential optimizations, FindBugs to (coincidentally) find bugs. I should mention Checkstyle again since it can also detect bug patterns. The situation is simple: the more code analysis tools you run on your code the more you will be able to fix problems before they bite you.

6. Use a continuous integration system

I will unleash my secret finishing move on the next guy who tells me: “but it works on my machine”. A continuous integration system is a referee. If the ref says the build fails because it is broken or because some test fails, it’s because it is. So, go fix it. The ref is always right even when “it works on my machine”. How does it do that? At regular intervals, it tries to build the latest version of your code and if anything goes wrong, it fires notifications — generally emails — to whoever is concerned. Receiving these notifications is not such a bad news: you have identified a problem in your code. Use your continuous integration system to run the code analysis tools and fail the build if these tools report problems. You can use CruiseControl, AntHill, DamageControl or write your own with cron+make+sendmail, but please use a continuous integration system.

7. Write less code

Aspire at writing code like a Zen master writes a Koan:

Monk: Does a dog have Buddha nature or not?
Zhaozhou: Wú.

There are two principles to assist you in your quest for minimalist code: KISS and DRY. “Keep It Simple Stupid”: do what is required and no more. Focus on a clean and simple implementation. “Don’t Repeat Yourself”: avoid duplicating code. Refactor mercilessly. This will decrease the size of your code-base, which is a Good-Thing™ because the less code you write, the less bugs you write.

8. Performance is overrated

I will probably have a contract on my head after this point, that’s what blogging is about, no? Writing fast code is a two step process:

  1. get the code to work,
  2. stop.

In case this was unclear: do not optimize the code. In the vast majority of cases, the code you are about to optimize is not a bottleneck. Use a profiler on a system running realistic data and identify the bottlenecks. Only then can you start working out how to eliminate them. Very often you will not have to change a single interface, only the implementation will require changes.

9. Read, read, read

Read books about software development. You must read the GoF book about Design Patterns and put it to good use. You must pick up Martin Fowler’s Refactoring, Code Complete by Steve McConnell. There are countless others. One of the first book to really open my eyes on developing good code was Writing Solid Code by Steve Maguire.
Read books about other programming languages too, you will frequently discover programming concepts that you might be able to port to your environment.

10. Use common sense

Common sense is your best friend to beat bad code and it’s free! Common sense is what dictates the previous nine points.

I hope you found these tips interesting and entertaining too! I am looking forward to your comments. I leave you with Zhaozhou to conclude this post: Wú!.

technorati tags:, ,

Advertisements

19 Responses to “Producing and maintaining high-quality code”


  1. A good exhaustive list. I try to follow the design principles in addition to the design patterns, as much as possible. I also look at reference implementations or other project codes to gain a better understanding of what others are upto.


  2. Welcome back Abhijit, you make a very good point. Thanks!

  3. Marc Says:

    Interesting post. Good advice. Thanks!


  4. Good post, some very useful advice there.

  5. Prashanth Says:

    Especially agree with point 7 :-)
    The lesser the code, the lesser the bugs

    Excellent post!


  6. Thanks guys for the positive feedback!


  7. I like to see people pushing continuous integration and unit testing. I find that those two are points from xp that are more or less exclusively positive, whereas things like pair programming present benefits but also drawbacks.
    However, I don’t understand what it is with these coding standards that everybody wants to enforce. I know it’s one of the twelve practices of xp and considered essential in many other methodologies, but is it really that important? I can see that there might be something to gain from a uniform formatting, but I am not sure that the cost/benefit balance is right. Enforcing such a standard does take some time, and I find that reading somebody else’s code which is written with a completely different standard than mine takes me but a split second to adapt to.


  8. Hi Kristian,
    regarding pair programming, the only drawback I can think of right now is that it is tough: it requires a lot of discipline and efforts. In my experience, certain people just cannot pair.
    Concerning the enforcement of coding standards, the cost is entirely related to the quality of the tools at your disposal. Eclipse + Checkstyle plugin is a really cheap solution for Java. It just adds warnings to the code, on the fly, when you break the standard (on which you have full control).
    Not all languages have this kind of high-quality tool but most have formatting tools or editors that at the very least give you a uniform indentation. Running such a tool before commiting to the source code repository is a very low cost operation.
    The benefits are not neglectable. A uniform looking code is very easy to follow. By the way, I actually think Python’s usage of indentation to specify blocks is a good thing as any Python developer can at a glance see the structure of a piece of code.
    Thanks for your comment!

  9. quag Says:

    Thanks for the list Olivier. I’ll be forcing^Wmentioning it to a few developers around me. :-)

    Do you know of other good articles for introducing people to good development techniques?

    Thanks,
    Quag.


  10. Hi Quag,
    Martin Fowler’s site is a gold mine. <nerd>Computing its signal to noise ratio raises division by zero exceptions!</nerd>
    You make me realize I do not link enough. I have to update my blogroll.
    See you on #io!

  11. twifkak Says:

    Two questions:

    Know any good checkstyle/lint tools for Ruby?
    Know any good links for aspiring Coding Guidelines authors? Heck, any templates I can pillage? :P


  12. Twifkak,

    I am not aware of any usable checkstyle/lint tools for Ruby. CheckR is at the planning stage and looks promising. If you ever hear of one, I am interested too!

    Regarding templates, I recommend checking out Sun’s code conventions for Java, and the GNU coding standards. Whether you like them or not, they are a good source of inspiration. Googling “coding standard” will give you plenty of examples. By the way, if I remember correctly — since I cannot find it — the code conventions in Rails are along the lines of “look at the existing code and try to integrate your code seemlessly”.

  13. eljunior Says:

    Good work!
    The **3. Talk to your cardboard friend** is specially a good thing for me. I think it usually is useful when I didn’t give the necessary attention to **1. Understand the problem** and **10. Use common sense**. :-)

  14. Axel Plinge Says:

    Could not agree more. I’ve been coding for almost 18 years, 10 years OO, and all points match my experience.
    The only thing I would add to day is: Use dynamic languages like Ruby to broaden your Java/C++/C# horizon, it will reflect very well on your coding style.

  15. Tony Byrne Says:

    In reply to Kristian Dupont’s comment about the value of a coding standard.

    For me it’s more important to agree on idiom than it is to agree on where to put the braces and whether to use tabs or spaces for indentation, although I do prefer consistency here too.

    Braces and tabs are easily handled by tools and assuming the team can agree something, it helps to pick a standard for these things.

    Much more interesting however, is how the individuals on the team choose to express themselves in a language. To use a Perl example, one man’s:

    my %hash = map { getkey($_) -> $_ } @array;

    is another’s

    my %hash = ();
    foreach (@array) {
    $hash{getkey($_) = $_;
    }

    These sorts of differences in personal style really can impact on the understandability of the code. IMHO, XP’s idea of coding style implicitly includes choice of idiom. After all, the XP ideal is that it should not be possible to tell one person’s code from another’s on the same XP team.

  16. Govind Says:

    informative….thanks

  17. naisioxerloro Says:

    Hi.
    Good design, who make it?


Comments are closed.

%d bloggers like this: