Java Documentation – Writing for Well-Understood Methods Like equals

commentsjava

Is it a good practice to write comments for widely known methods like equals, compareTo etc?

Consider the below code.

 /**
 * This method compares the equality of the current object 
  with the object of same type
 */
@Override
public boolean equals(Object obj) {

               //code for equals

     }

My company madates to enter comments like the above.Is the above Javadoc comment required?
Is it not obvious and well understood what the equals method and the likes (compare,compareTo) etc does?

What are your suggestions?

Best Answer

JavaDoc already supports the inheriting of comments. According to the documentation, "constructors, fields and nested classes do not inherit doc comments", but methods such as equals() will. Since the Object class has a well-documented equals() method, you should just be able to inherit that documentation without a problem.

The documentation for the method needs to come from somewhere so that it is accessible in your IDE and in the generated web documentation. Explicitly rewriting accurate and comprehensive comments that exist in a superclass is not necessary, and I would argue clutters the code files.

If this is corporate policy, then you have two options. You can go along with it sliently, and deal with the extra effort of writing and maintaining documentation (often in violation of the DRY principle, which can also be applied to documents as well as code). The other option would be to seek company policy - explain why this policy isn't a good idea and the benefits of changing it (in terms of time, money, effort, quality - things that management understands).

Related Topic