How to JavaDoc (efficient and maintainable) - 6 steps 📎
Most of the JavaDoc comments are worthless. They describe redundantly already existing information and obvious facts. Many developers are indirectly forced (by e.g. QA) to write dumb Javadoc, only to increase some metrics. However this approach is really expensive, because:
- Someone has to write the JavaDoc
- ...and even worse - in the mainainance phase all developers are forced to filter out relevant things and ignore worthless information
The classic sample is:
/**
* This is a setter which sets the name
@param name - the name to be set
*/
public void setName(String name) {...
The already existing information from the method's signature is replicated to the javadoc. In my opinion such a javadoc is superfluos, every java developer knows what getters and setters are. The same anti-pattern is often applied to document other elements - not only obvious Java Bean "components".
Instead of writing superfluos documentation, you could also introduce a new Javadoc tag or annotation to mark such use cases e.g. @Obvious. In this particular case the QAs should be happy with the doc coverage and developers could silently ignore the doc.
Really good javadoc should be written accoding to the following rules:
- Document the background knowledge, the intention and not the result
- Try to capture the concepts in a central place (e.g. wiki) - and only reference to the contents
- Document obvious facts with marker tags - don't describe them over and over again (be DRY) [see Marker Annotation in p4j5]
- Include in your documentation samples, how-to etc. (source code rules)
- Don't allow default javadoc comments generated by the IDE
- Sometime "No Doc, is the Best Doc" - try to minimize the amount of documentation and describe only the key concepts.