Documentation: Update It Or Lose It
Posted by pramatr on February 17th, 2009
Over time I’m frequently restructuring and refactoring the code I work on to improve the design and simplify many of the balls of mud I find along the way. If I break some of that code my unit tests shout at me and if they don’t my continuous integration environment shouts at me when I’ve broken one of the integration tests. One area of the code that doesn’t receive the same attention however is the documentation.
I love a well documented API as much as the next developer. I also am fighting a constant battle to improve my JavaDoc skills, trying to write to the same quality that I see in many other projects. But is excellent documentation really enough? It can’t just be excellent when it’s written it needs to be constantly maintained to this same level over time.
It’s a pretty common occurrence that I can look at a section of code and find documentation that has nothing to do with the method it belongs to. The intention revealing name sounds nothing like the documentation which describes what it’s supposed to be doing. Somewhere in the mists of time, the intention of the method and the documentation parted company; it is documentation no more it is ex-documentation. The problem here however is that there’s nothing to catch this issue. If an extra argument is added, Eclipse might display a warning telling me it’s missing from the documentation, but the actual context of the documentation can be completely wrong and I am none the wiser.
Although this incorrect documentation may seem fairly harmless to some, the reason it was supposed to be there in the first place is to the give the user of the API information on the method contract and the expected outcomes. If this information is completely wrong however it introduces confusion and also potential misuse of the API. After much wasted time and several grey hairs later I recently filed a couple of JIRA reports about popular open source frameworks which did exactly this. After my code just didn’t work and the unit tests failed, it took me a number of minutes to realise that the JavaDoc description of expected events just didn’t reflect what was actually going on in the code.
One approach to solving this problem is to include the documentation in the frequent code reviews. Code that doesn’t have documentation or has incorrect documentation can’t be considered complete, thus doesn’t pass the review. Developers need to make sure however, that they treat the documentation with the same respect that they give to their code and their tests. When dealing with documentation I’d much sooner see a method with no documentation than something that is completely wrong. I do want a good level of documentation in the code I work on but there is a very simple rule; update it or lose it.