Stephen Colebourne's blog: Javadoc coding standards
Javadoc coding standards
Javadoc is a key part of coding in Java, yet there is relatively little discussion of what makes good Javadoc style - a coding standard.
Javadoc coding standard
These are the standards I tend to use when writing Javadoc. Since personal tastes differ, I've tried to explain some of the rationale for some of my choices. Bear in mind that this is more about the formatting of Javadoc, than the content of Javadoc.
There is an Oracle guide which is longer and more detailed than this one. The two agree in most places, however these guidelines are more explicit about HTML tags, two spaces in @param and null-specification, and differ in line lengths and sentence layout.
Each of the guidelines below consists of a short description of the rule and an explanation, which may include an example:
Write Javadoc to be read as source code
When we think of "Javadoc" we often think of the online Javadoc HTML pages. However, this is not the only way that Javadoc is consumed. A key way of absorbing Javadoc is reading source code, either of code you or your team wrote, or third party libraries. Making Javadoc readable as source code is critical, and these standards are guided by this principal.
Public and protected
All public and protected methods should be fully defined with Javadoc. Package and private methods do not have to be, but may benefit from it.
If a method is overridden in a subclass, Javadoc should only be present if it says something distinct to the original definition of the method. The @Override annotation should be used to indicate to source code readers that the Javadoc is inherited in addition to its normal meaning.
Read full article from Stephen Colebourne's blog: Javadoc coding standards
No comments:
Post a Comment