Mike Clark

Someone was recently explaining to me how he always wrote the JavaDoc before writing each method. It helped him mentally work through the signature of the method and what it should do. A specification of the method, if you will. I can certainly understand how that might be beneficial, but I lack the discipline it requires. Indeed, I'm quite sure I'd forget to update the JavaDoc to keep it in synch with the method. And the refactoring tools I use wouldn't help me much either. They don't comprende JavaDoc.

Alas, I'm much too lazy and forgetful to keep JavaDoc in synch at the method level. Instead, I just write an executable test before writing the method that makes it pass. The act of writing the test helps me design the method from the outside. Running the test tells me if it does the right thing. Then I let the computer do all the hard work. If later I change the method signature or the result the method produces, the tests will tell me that my "documentation" is out of synch. And if someone wants to see how to use the method, the test is there as a specification by example. They can run it and the gears inside actually turn. Then they can fiddle with the test and see what happens. I figure if someone is looking at the JavaDoc for a class, their intent is to use it somehow. I'd rather just give them a working test that demonstrates the features of the class.

That being said, I do write some JavaDoc, but only if I can't express the same information in code and tests. In other words, the JavaDoc has to do something for its reader, not just pacify some documentation standard. Color me lazy and forgetful.