Title: Professionalism in Programming #9

There is a huge difference between working code, correct code and good code. M. A. Jackson wrote "The beginning of wisdom for a software engineer is to recognise the difference between getting a program to work, and getting it right." [Jackson] You can write code that 'works' most of the time. You feed it the usual set of inputs, it gives the usual set of outputs. But give it something surprising and it might just fall over. 'Correct' code won't fall over. For all possible sets of inputs the output will be correct^[1]. However, not all correct code is 'good' code - the logic may be hard to follow, the code may be contrived, it may be practically impossible to maintain.

Good code is what we should aim for. It is robust, efficient enough, and of course correct. Industrial strength code will not crash or produce incorrect results when given unusual inputs. It will also satisfy other requirements such as thread safety, timing constraints and re-entrancy.

There are many methodologies for producing code: various object-orientated approaches, component based models, structured design, VDM and so on. Defensive programming is an approach that can be applied to any of these. It's not so much a formal methodology as a set of rules of thumb. It is one way to ensure that our code is good.

As the name suggests, defensive programming is careful, guarded programming. When we write code it is all too easy to make a set of assumptions about how it should run, how it will be called, etc. We then carry on our work using this set of assumptions for months, as they fade and distort in our minds.

When we program defensively, we don't make any assumptions. We never assume "it can't happen" (I won't ever be called like that, this piece of code will always work...). Experience tells us that the only thing you can be certain about is that your code will somehow, one day, go wrong. Murphy's law says, "if it can go wrong, it will". Murphy was a wise man. So defensive programming prevents accidents by foreseeing them, or at least foreguessing them - figuring out what can go wrong at each stage in the code.

Is this paranoid? Well, it doesn't hurt to be a little paranoid. In fact, it makes a lot of sense. You will forget the set of assumptions you make as your code evolves (real code does evolve). Other programmers won't have any knowledge of the assumptions in your head, or will just make invalid assumptions about what your code can do. Software evolution exposes weaknesses. Code growth hides original simple assumptions. A little paranoia at the outset can make code a lot more robust in the long run.

Add to this the fact that things can go wrong that neither you nor your users have any control over at all, disks get full, networks fail, computers crash. Remember, it's never actually the software that 'fails' - the software always does what you told it to. It's the actual algorithms or client code that introduces faults in the system. If we write code defensively we attempt to prevent, or at the very least observe when our code is called in such as way as to exhibit incorrect behaviour.

There are a number of techniques we can follow to apply the defensive programming approach to our code. Bear in mind these are all much easier to apply as you start writing code, rather than retrofit onto existent code. The first set we'll think about do not relate so much to the assumptions we make as much as they are just good practise for writing robust code. They are ways of avoiding the possibility of future problems.

Running a static code checker (e.g. lint) as mentioned in the previous column can uncover a number of these problems, but not the whole lot. There is no substitute for careful programming.

We've talked about the set of assumptions we make as we program. How can we incorporate this set of assumptions in our code? We can write a little extra code to check these conditions. This code would act as the documentation for the assumptions, making them explicit rather than implicit^[3] In doing this we're codifying the constraints on program functionality and behaviour. What do we want the program to do if a constraint is broken? Since this kind of constraint will be more than a simple detectable and correctable run time error (we should already be checking for and handling those), it must be a flaw in the program logic. There are few possibilities:

For example, if it is invalid to call void a(foo *ptr) with ptr = 0 because ptr will be dereferenced almost immediately, the last two are the most plausible candidates. It's probably best to abort the program completely, since deferencing a null pointer can lead to all sorts of catastrophes on unprotected operating systems.

There are a number of different scenarios in which constraints are used:

The first two are frustrating to implement in C/C++ - with multiple exit points in a function things can get messy when you incorporate a post condition. Eiffel is much better in this respect, with pre/post conditions supported in the core language. It can also check that the constraint's conditional code does not have any side effects.

However tedious, good constraints expressed inline in the code makes the code clearer and more maintainable. This technique is also known as design by contract.

There are a number of different problems you can guard against with such constraints. For example, you can:

The first two of these examples are particularly C/C++ focused. Java has its own ways of avoiding some of these pitfalls, as do Pascal and Ada.

There is the perfectly valid question: just how much constraint checking should you do? Placing a check on every other line might be a bit extreme. As with many such things, the correct balance becomes clearer as the programmer gets more mature. Better too much than too little? It would be possible for too many constraint checks to obfuscate the logic in the code. "Readability is the best single criterion of program quality: if a program is easy to read, it is probably a good program; if it is hard to read, it probably isn't good." [ST]

Realistically, putting pre- and post-conditions in major functions plus invariants in the key loops is more than sufficient.

Now this kind of constraint checking is usually only required during the development and debugging stages of program construction. Once we have used the constraints to convince ourselves (wrongly or rightly) that the program logic is correct, we would ideally remove them so as not to incur an unnecessary runtime overhead.

The standard C and C++ libraries provide us with a single mechanism to implement these constraints - assert. assert acts as a procedural firewall, testing the logic in its parameter. It is provided as an alarm for the developer to show incorrect program behaviour and should not be allowed to trigger in customer-facing code. If the assertion's constraint is satisfied execution continues, otherwise the program aborts. If the assertion is triggered, the program will output to standard error a message something like this (taken from from gcc) before exiting:

  a.out: bugged.cpp:10: int main ():
  Assertion "1 == 0" failed.

assert is implemented as a preprocessor macro which means it sits more naturally in a C environment than a C++ one^[5]. To use assert you must #include assert.h. Then you can write in your function something like assert(ptr != 0); Preprocessor magic allows us to remove all assertions in a "production build" by specifying the NDEBUG flag to the compiler. All asserts will be removed, and their conditionals will not be evaluated. This means that in production builds asserts have no overhead at all.

However, whether or not assertions should be completely removed as opposed to just being made "non fatal" is a debatable issue. There is a school of thought that says by removing them you are now testing a completely different piece of code^[6]. Others say that the overhead of assertions are not acceptable in a release build. One area we must definitely be wary of is that our assertions must not have any side effects. For example, if you mistakenly wrote

int i = 5;
assert(i = 6); // hmm - should have typed more carefully!
printf("i is %d\n", i);

The assertion will clearly never trigger in a debug build; its value is 6 (near enough 'true' for C). However, in a release build, the assert line will be removed completely and the printf will produce different output. This can be the cause of subtle problems late in product development. It's quite hard to guard against bugs in the bug-checking code! It's not hard to envision situations where the assertions might have more hidden side effects. For example, if you assert(invariants()); yet the invariants() function has a side effect, it's not so easy to see immediately in the code.

Since the assertions can be removed for production code, it is also vital that only logical constraint testing is done with assert and no real error condition testing. You wouldn't want to compile that out of your code!

Whilst debugging your program, when you discover and fix a fault, it is good practice to slip an assertion in where the fault was fixed, then you can ensure that you won't be bitten twice. If nothing else, this would act as a warning sign to people maintaining the code in the future.

A common C++ technique for writing constraints when testing classes is to add a single member function to each class called bool invariant(). (Naturally this function should have no side effects). Now an assert can be put at the beginning and end of each member function calling this invariant. (The exceptions to this rule being no assertion at the beginning of a constructor or at the end of the destructor, for obvious reasons). For example, in your circle class your invariant may check that radius != 0 since that would be invalid object state and cause later calculations to fail (perhaps with a divide by zero).

Whilst writing this the thought occurred to me, what is the opposite of defensive programming? It is offensive programming of course! Now, there are a number of programmers I know who you could call 'offensive programmers,' but maybe there's more to it than just swearing whilst writing code?

It stands to reason that this 'offensive' logical opposite would be trying to break things in the code rather than guard against problems. This is, actively attacking the code rather than securing it. I'd call that testing.

That means we should be all offensive programmers.

It is important to generate code that is not just correct, but is also good. It needs to be clear, documenting all the assumptions made. This way it will be easier to maintain with fewer bugs. Defensive programming is a method of expecting the worst and being prepared for it.

Many companies say that they employ defensive programming. Look at their code bases - do they really?