我应该记录重写的hashCode（）和toString（）吗？

Question

Is it desirable to document the overriden hashCode() and toString() or similar methods in Java? (not including equals() and similar of course) What are the conventions?

Answer 1

From Oracle's JavaDoc Guide:

So if the documentation of the overridden or implemented method is sufficient, you do not need to add documentation for m() .

If your hashCode or toString are doing something different to the documentation in Object then you need to amend the code rather than the documentation. As anyone using these methods without access to the JavaDoc will expect them to behave as documented in Object.

JavaDoc:

hashCode toString

Answer 2

如果您使用一些需要记录的特殊算法，我将编写内联注释// ...，但这对于依赖于继承的Javadoc表示的合同的API用户来说应该无关紧要，所以我不会将其写为Javadoc注释。

Answer 3

Sometimes it is useful to document them. For instance, if an object is intended to be a value returned by a Swing model (ListModel, TableModel, etc.), its toString method may return a display string intended to be displayed to the user, rather than a string meant for debugging. I often like to make it clear whether an object's toString is suitable for display to an end user.

I will document equals to indicate which properties or what state constitutes equality, like URI.equals and List.equals do. Similarly, it is useful to point out the properties or state on which hashCode relies, especially for mutable objects, since it allows a developer to avoid changing that state when the object is used as a hash key.

Answer 4

When there is a reason to have a specified algorithm for computing the hash-code, you should document that algorithm for the hashCode() method. Java itself does this for String.hashCode() :

a hash code for this string. The hash code for a String object is computed as

 s[0]*31^(n-1) + s[1]*31^(n-2) + ... + s[n-1] 

using int arithmetic, where s[i] is the ith character of the string, n is the length of the string, and ^ indicates exponentiation. (The hash value of the empty string is zero.)

For most other cases, however, the general contract of Object.hashCode() requiring it to be consistent with equals() is enough documentation.

Bloch in Effective Java recommends documenting the format of the toString() message for value classes . He also notes that in that case you should provide a also provide a parsing function (a static factory method) that creates an object of the class given its String representation..

Answer 5

You shouldn't override the Object class's documentation of these methods, since it describes the contract that all implementations (including yours) can be expected to follow. It may be appropriate to extend the inherited documentation with additional notes about your implementation. You can do that like this:

/**
 * {@inheritDoc}
 * <p>
 * In this implementation...
 */

The Javadoc tool will insert the superclass documentation in place of the {@inheritDoc} tag, so that the output will consist of that superclass documentation followed by your additional notes.