I had to build a complex module this last week and hand it to another developer to integrate into the app. This reminded me of a usually unmentioned value of unit tests: documentation.

Unit tests are all about writing little test jackets of code that exercise the production code and make sure it works. At their best they are designed to test the output and scream it if is not right, though lots of tests just print out something for a human to examine and verify.

I usually write unit tests to verify my code anyway, so of course I delivered my test to the other developer so that she could see how to call my module. She could run the test, step through the code and explore how it works, and she could verify my assumptions about the inputs (the spec was vague) because she is getting the real inputs and I had to mock up mine for the test.

When I have to work with code I don’t know I usually look for a unit test first to tell me how it works. Perhaps projects should consider putting less effort into documentation (which no one reads) and more into unit tests. Documentation drifts out of date. Unit tests either work or they don’t and even the exercise of fixing them can be useful in finding out how things work. Better to keep them maintained than fix them on the fly though.