[prog] Unit testing

[Almut Behrens]

On Thu, Sep 02, 2004 at 10:32:29AM +0200, drichter at essi.fr wrote:
> 
> I've discovered the power of unit testing. I use it even in my personal 
> projects, and it's all the more important when several people are hacking the 
> same code base.
> 
> But I have a question: how well should you document your unit tests?
> (...)  Should unit tests be coded quickly or well?

Of course, we all know we should always produce good documention for
_everything_ we code.  Likewise, we all know why good documentation
often doesn't get written: the ever-present lack of time.  Surely,
there's no denying we're all human, so pure laziness and reluctance
to do things we don't enjoy cannot be ruled out as another important
factor -- but we'll ignore that for now.
(Yes, I know, along similar lines you might ask yourself: why, then, 
if she's got no time, does she post to linuxchix several times a day? 
Well, I have no short answer on that one... ;)

Anyway, due to time being precious, I think it's important to find some
compromise between the short-term perspective of getting things done in
time vs. producing long-term maintainable code. If you too much neglect
the latter in favor of the former, you risk having to spend even more
time later on, so it simply won't pay off in the long run.

My rather simple strategy is to generally write as much comprehensible
documentation that at least I myself can figure out what's going on,
some months later -- with efforts somewhat weighted by the 'relevance'
or the expected time-to-live of the code.  This minimally comprises
concise inline comments -- preferably with some short outline of the
general idea being added in normal prose or as snappy diagrams  (if
you really have the time to create all those neat UML diagrams, then I
certainly won't restrain you from doing so...)
A clear design and modularisation always helps, of course.

Regrettably, it took me quite some time to admit to myself, and truly
accept, that my memory isn't as good as I'd like it to be...  In that
respect (i.e. some months later) the original coder is often not much
better off than anyone else with the same general level of expertise 
(BTW, this has nothing to do with whether you wrote your code in perl,
or not ;).  IOW, comments should ideally be written as if you were
explaining matters to someone else.

As to the weighting: on the one end there are throw-away scripts or
programs where I'm just quickly trying out an idea seperately, without
having to build and run the entire application. They typically don't
need any comments at all, IMO.  On the other end is code that you can
anticipate to be read and maintained by many people for many years to
come  (and always consider that it still might need to be understood,
even if you don't anticipate it now -- think of all that long-forgotten
COBOL code that totally unexpectedly needed to be evaluated for Y2K
compatibility...).

For unit tests, specifically, I'd say that their code is almost as
important as any 'regular' application code.  If you can't rely on a
test producing useful results, because you no longer really know what
it's doing or whether it would still work under slightly modified
circumstances, it's not much use having it. In fact, it might even be
worse than not having the test at all, as it might lead to some false
sense of everything being well.

So, my short answer is:  document unit tests (almost) as well as any
other code, and try to avoid 'slapping things together'.

Unfortunately, I don't know of a better strategy. If someone does, I'm
all ears :)

Just my 2 cents -- not too earth-shakingly brilliant, I guess :)

Almut


P.S.:  an interesting, somewhat related issue: automatic testing of
tests.  See, for example (for JUnit): http://jester.sourceforge.net/