Source Code Documentation

Assumptions:

1. Javadoc is a good practice approach for code documentation.
2. Javadoc should always be written in a manner that allows for simultaneous consumption of source code and javadoc. Think of javadoc as being an essential part of the code, so making Javadoc readable as source code is critical.

Minimum Requirements:

Javadoc:

• For classes: names the author (@author) with QNumber AND name (data privacy?)
• contains a complete description of what the code is doing
• Describes Input parameters, and their allowed values
• Explains the return statement, and the possible values
• Specifies the thrown Exception, and the situations it is thrown in (if applicable)
• If own Data Types are used, they is a link to their definition in the javadoc. {@link package.class}
• If a method is equivalent, or you want to highlight the call to another method, it is linked. (@link package.class#member)
• When working with APIs
• use @since to show when this method was introduced
• use @deprecate annotation to specify when this call will be deprecated

Form:

/**
* This is a very special method that show the usage of Javadoc. Calls {@link #anotherMethod()}.
* @param description The method’s description. Cannot be {@code null}
* @return {@code true} if the method was annotated correctly, {@code false} if not
* @since version 1.0
* @deprecated version 2.0
* @throws MethodDescriptionException if the description parameter was {@code null}
**/

Method:

• Method name and Parameter values have meaningful, short names
• Method length < 20 LoC
• Inline Comments wherever a complex task happens that cannot be put in its own method

Procedure:

• Code Documentation (a lá mavensite) is generated automatically on build time
• Code Documentation is published to a specified location

Good practice examples:

https://blog.joda.org/2012/11/javadoc-coding-standards.html

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.

Last but not least the official Oracle site with good practices.

https://www.oracle.com/technical-resources/articles/java/javadoc-tool.html