When adding documentation to my Java program, I realize that most classes require a serialVersionUID constant property to be declared. How exactly should I document this property? And do I document it differently if I used a default vs. generated serial version UID?
/**
* What goes here? "A unique serial version identifier"
*/
private static final long serialVersionUID = -8922096951749901688L;
First of all, the serialVersionUID comment you provided seems right but unnecessary.
The serialVersionUID is required as part of a Serializable object (not all java classes) and is used during the serialization / deserialization of this objects.
As a general rule. ALWAYS CHECK THE API
in this case, Serializable API, at the bottom!!
The serialization runtime associates with each serializable class a version number, called a serialVersionUID, which is used during deserialization to verify that the sender and receiver of a serialized object have loaded classes for that object that are compatible with respect to serialization. If the receiver has loaded a class for the object that has a different serialVersionUID than that of the corresponding sender's class, then deserialization will result in an InvalidClassException. A serializable class can declare its own serialVersionUID explicitly by declaring a field named "serialVersionUID" that must be static, final, and of type long:
ANY-ACCESS-MODIFIER static final long serialVersionUID = 42L;
So you're saying that it should actually not be documented whatsoever because there is javadoc for it already? When I omit the javadoc and mouseover it, it does not show anything
:/
It's part of Serializable interface, so IMHO is not necessary... anyway, you can use your own comment + @see annotation. Something like this (not sure if will work, cannot create javadoc now...)
/**
* A unique serial version identifier
* @see Serializable#serialVersionUID
*/