Your current comment is incorrect. Your method signature is correct in taking a generic Object, but your comment says 'object of same type'.
–
c_makerSep 7 '11 at 12:28

3

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.
–
David ThornleySep 7 '11 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.
–
Vinoth Kumar C MSep 7 '11 at 14:01

5

@Vinoth: the "meaningful way" is exactly what you need to document :)
–
c_makerSep 7 '11 at 14:33

7 Answers
7

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

I am aware about inheriting. But the company "mandates" us to write explicit java docs.
–
Vinoth Kumar C MSep 7 '11 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).
–
Thomas Owens♦Sep 7 '11 at 12:31

@Thomas: There is the beg forgiveness rather than ask permission option: Just silently bend the rules and see if anyone complains.
–
dsimchaSep 7 '11 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.
–
Thomas Owens♦Sep 7 '11 at 15:19

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.
–
NicholasSep 7 '11 at 15:46

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:

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.

"the object" should read "an object"

"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:

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

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.

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.