[prog] Unit testing

[Akkana Peck]

drichter at essi.fr writes:
> But I have a question: how well should you document your unit tests? Mine often 
> have code that's difficult to follow because they're just slapped together. 
> This makes for fast coding, which is important for two reasons. First, you want 
> a lot of unit tests. Second, your unit tests may be obsolete with the next 
> revision of the program, so you shouldn't spend too much time on them.
[ ... ]
> So what do you think? Should unit tests be coded quickly or well?

I vote for "well".

Admittedly, it's better to have any test than no test at all.
But unit tests are likely to be run and maintained by someone
other than the person who wrote the code; they're especially
important for QA people, or for someone who inherits the code
later.  If the test doesn't provide enough information about
what went wrong, future owners of the code will just ignore it
and stop running it.

I don't agree with the "will be obsolete with the next revision"
argument: unit tests (the most useful ones, anyway) test
functionality of the program or library, not intimate details
of how the code works.  The functionality isn't likely to change
that much in the next revision; and if it changes a little, a
well written unit test will be easy to update to test the revised
functionality, while a poorly written one may end up being obsolete
because no one can figure out how to update it.

Obviously this is a continuum.  You don't need to spend weeks on
design reviews for a unit test.  But I do think it's well worth
spending a little extra time writing comments about what the code
is doing, thinking about maintainability (by someone other than
the author), and emitting long and clear explanations when error
conditions occur, suggesting what might have gone wrong.

It's also helpful to point to more information.  I found that a lot
of people were ignoring one unit test I'd written, or coming to me
when they broke something rather than trying to figure it out on
their own.  I wrote a web page to go on the documentation site
explaining how that set of tests worked, and giving hints for how
to chase down sources of errors, and changed the unit test to
include the url to that web page.  It seemed to help.

	...Akkana