10

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?

Improve this question
4
  • 3
    Your current comment is incorrect. Your method signature is correct in taking a generic Object, but your comment says 'object of same type'. Commented Sep 7, 2011 at 12:28
  • 4
    I'd rather see a comment explaining what equality means for this object. "Equality" is a slippery term. In Common Lisp, there are numerous equality functions, and you pick the appropriate one on use. Commented Sep 7, 2011 at 13:44
  • In this case, I am referring to two objects being equal in a "meaningful way". For example two Employee objects are equal if they have the same employee ID, rather than say they wear the same color shirt. Commented Sep 7, 2011 at 14:01
  • 6
    @Vinoth: the "meaningful way" is exactly what you need to document :) Commented Sep 7, 2011 at 14:33

7 Answers 7

Reset to default
6

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).

Improve this answer
4
  • I am aware about inheriting. But the company "mandates" us to write explicit java docs. Commented Sep 7, 2011 at 12:26
  • 3
    @Vinoth If that's company policy, then there's nothing you can do other than either writing them or seeking to change the policy. If you are using modern development tools, then that policy is out of date. What drives this policy? JavaDoc comments are turned into web pages and modern IDEs let you view the JavaDoc comments as you are writing software, regardless of where the comment comes from (explicit or inherited). Commented Sep 7, 2011 at 12:31
  • @Thomas: There is the beg forgiveness rather than ask permission option: Just silently bend the rules and see if anyone complains. Commented Sep 7, 2011 at 15:16
  • @dsimcha Perhaps, but if it's repeated, that could be bad for the job. This isn't a one-or-two-off thing. Commented Sep 7, 2011 at 15:19
9

In my team we usually use the @inheritDoc annotation for equals() and hashcode() but I wish we did not.

For these two methods I always have to look at the implementation. Since you are overriding a method, that means you want it to do something different. I think this deserves its own documentation.

It is good to at least document what attributes participate in the method and even maybe why that is.

Improve this answer
1
  • 1
    Your last statement is the best reason for documenting it yourself. Explain what it's doing. Sure equal() might compare every element in the class, or you may want it to just compare all the string fields, or something else. Commented Sep 7, 2011 at 15:46
2

Remember that comments help developers of all sort if they are correct.

The problem is that they are sometimes incomplete and not accurate.

To be honest comparing 2 objects may be tricky (e.g. comparing 2 invoice objects), also your method may evolve with time and would then need to be commented.

Showing the method objective, rules, etc. in a "useful and meaningful" comment is a good thing.

Improve this answer
2

It is extremely poor practice to litter code with vacuous comments like:

/**
 * This method compares the equality of the current object with the object of same type...
 */

This says nothing useful. Worse, it is poor in both style and grammar:

  1. Comments should never start with "This method" or "This class" or "This" anything. The comment is associated with a method or class by its location in the source file.

  2. "the object" should read "an object"

  3. "Compares the equality" makes sense only if the one object can have more "equality" than another. This function does not compare "equality"; it compares objects to determine their equality with each other.

Instead, the comment should indicate when the two objects are considered equal. Here, I would omit the method description entirely, and only document the return value, for example:

public class Fraction {
  private int numerator, denominator;
  /**
   * @return true if <i>this</i> is numerically equal to <i>other</i>
   */
  public boolean equals(Fraction other) {
    return numerator * other.denominator == other.numerator * denominator;
  }
...
}

Generated comments for trivial get/set methods are the worst of all.

Improve this answer
1

Our coding standard dictates that when overriding a method it is not necessary to document it unless, in overriding it, the documentation in the parent class or interface is no longer accurate and comprehensive for the sub- or implementing-class.

For equals, we might want to note that the comparison is only done on a primary key when comparing a database backed entity as that is not entirely consistent with the documentation for Object.equals().

Improve this answer
0

In my opinion, and I think this may be controversial, you should indicate in the comment in which class you've overridden the class. Then six months down the line when you wonder whether it's implemented or not you'll be able to see without opening the class up.

Improve this answer
0

Knowing that those methods are common and most of the developers will know what they are for then, IMO, you won't need to put any comments there. Comments are not that reliable in the long run as there are chances that these may not get updated when the implementation is updated and might cause confusion. So it is always better to make your code readable as this is what you can mostly trust.

Furthermore, I would say that if the code you are creating/editing is not for a public API then just leave out the javadocs for common methods as these will just add clutter and noise.

Improve this answer

Start asking to get answers

Find the answer to your question by asking.

Ask question

Explore related questions

See similar questions with these tags.