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.