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.
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:
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.