Unit Tests – Are They Used as Documentation?

documentationunit testing

I cannot count the number of times I read statements in the vein of 'unit tests are a very important source of documentation of the code under test'. I do not deny they are true.

But personally I haven't found myself using them as documentation, ever. For the typical frameworks I use, the method declarations document their behaviour and that's all I need. And I assume the unit tests backup everything stated in that documentation, plus likely some more internal stuff, so on one side it duplicates the ducumentation while on the other it might add some more that is irrelevant.

So the question is: when are unit tests used as documentation? When the comments do not cover everything? By developpers extending the source? And what do they expose that can be useful and relevant that the documentation itself cannot expose?

Best Answer

They're NOT an ABSOLUTE Reference Documentation

Note that a lot of the following applies to comments as well, as they can get out of sync with the code, like tests (though it's less enforceable).

So in the end, the best way to understand code is to have readable working code.

If at all possible and not writing hard-wired low-level code sections or particularly tricky conditions were additional documentation will be crucial.

  • Tests can be incomplete:
    • The API changed and wasn't tested,
    • The person who wrote the code wrote the tests for the easiest methods to test first instead of the most important methods to test, and then didn't have the time to finish.
  • Tests can be obsolete.
  • Tests can be short-circuited in non-obvious ways and not actually executed.

BUT They're STILL an HELPFUL Documentation Complement

However, when in doubt about what a particular class does, especially if rather lengthy, obscure and lacking comments (you know the kind...), I do quickly try to find its test class(es) and check:

  • what they actually try to check (gives a hint about the most important tidbits, except if the developer did the error mentioned above of only implementing the "easy" tests),
  • and if there are corner cases.

Plus, if written using a BDD-style, they give a rather good definition of the class's contract. Open your IDE (or use grep) to see only method names and tada: you have a list of behaviors.

Regressions and Bugs Need Tests Too

Also, it's a good practice to write tests for regression and for bug reports: you fix something, you write a test to reproduce the case. When looking back at them, it's a good way to find the relevant bug report and all the details about an old issue, for instance.

I'd say they're a good complement to real documentation, and at least a valuable resource in this regard. It's a good tool, if used properly. If you start testing early in your project, and make it a habit, it COULD be a very good reference documentation. On an existing project with bad coding habits already stenching the code base, handle them with care.

Related Topic