I am currently working with an application I don't know very well, written for a domain I'm not overly familiar with. This is not an uncommon situation for developers but it can be eased considerably with good documentation. I find that especially well written Javadoc are invaluable since they will show up in the IDE where I need it the most.
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 to relate 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 it 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.