This is the second week that I am documenting an unfinished JEE web based application. There is no inline comments except the author name that generated by IDE automatically. Some developers believe that a clear code doesn’t need to be documented (I mean inline comments specially Javadocs). However, among the years I’ve never seen a high standard code from famous companies such as Sun, Spring Source or Apache which doesn’t have inline comments over classes or major methods. Documenting is not a fun activity but it is necessary to make the code maintainable.
Wikipedia has defined Javadocs as following:
I like the idea of generating documents from source code. Because it keeps documents more synchronized with source code. It is always difficult to keep synchronized the code and the documents during a long time project. Moreover, Javadocs declares some tags to organize documents uniformly. This helps to define to the developers which tags are required for commenting and which one are optional.
Here are some simple tips to publish useable Javadocs:
1. You prefer to see an explanation to the class or methods instead of developer name. So always write a briefe description for the classes and methods before your write the @author name. Every process should defines it’s purpose, input parameters and return value. Method’s purpose should define at the first line of the comment. Input parameters and return value should be marked by @param and @return. See below example:
/** * Controls if a company existed or not. * @param name The name of column. * @param companyId The company ID that needs to be controlled if existed or not. * @return <code>true</code> if the company existed, otherwise <code>false</code> * @throws TCException */ public boolean exist(String name, Long companyId) throws TCException;
2. Use paragrafs by adding <p> tags to separate different concerns within the comment. For example it is better to use a paragraf to define association of the class with other ones.
3. Save your time by commenting super classes instead of descendants. Descendants inherit comments.
4. Respect the 20-80 rule to keep your document more describable. The 20-80 rule sugests to spend 80 percent of your time for documenting of 20% parts of the code that is more complex. Also spend 20% of your time for documenting 80% of the code that is simpler. Without a doubt the numbers are not always the same for different projects. Actually it is not about percents. It is about focusing on complexities and make them clear as simple parts.
5. Use the same syntax and uniform statements for the same definitions. This helps the user of Javadocs to use it faster.
6. During development and modification mark changed parts using //TODO comments to make it clear where needs to be commented again.
7. Let another developer tries your comments to find out if the comments are useful enough or not. This is the only way that makes you sure that you are generating right comments using Javadocs.