So what are the key things to think about when trying to write good documentation that other developers will read? I think the following points are important to think about that will make the documentation valuable.
- Document what the class/method/field is/should do, not how it does it. The intent of a class/method/field is not always evident from its name but a line or two of Javadoc will make it so.
- Use a language that is understandable by the client as well as the developers. I tend to find documentation written in the language of the domain the application is solving, with specific words explained, easier to understand since it's easy to relate to the real world problem then. If the documentation is overly technical it's difficult torelate it back to the clients requirements and needs.
- Remember who you are writing for. Generally Javadoc are written for other developers. Developers tend to understand and know technology so there is no need to tell them how something was solved. That should be obvious from reading the code and any in line comments. What needs to be described is how the code solves the real world problem and what part of the domain relates to.
- Javadocs are the contract. In my opinion Javadoc are used to detail what is the outcome of running a method or using a class/field. Like a contract. With some detail on how to use it if it's a public API method. It should not give me any detail on how it arrives to the result. This information is encapsulated in the code and the tests for the code.
If this documentation was readily available in the code base I am currently working my life would have been simpler. But then again perhaps it's a good thing that I start writing it since I now know what is missing. And perhaps the developer coming next will continue on this work since s/he will find other areas where documentation should have been added.