2

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;
rolling_codes
  • 15,174
  • 22
  • 76
  • 112

1 Answers1

2

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
 */
Community
  • 1
  • 1
Jordi Castilla
  • 26,609
  • 8
  • 70
  • 109
  • 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 :/ – rolling_codes Nov 03 '16 at 17:16
  • 2
    @NoodleofDeath Most Java developers will know what it is for. Probably the most helpful and simplest documentation you can give is to link to the [`Serializable`](http://docs.oracle.com/javase/8/docs/api/java/io/Serializable.html) javadocs and leave it. Of course you're free to add more information if you want. – 4castle Nov 03 '16 at 17:19
  • @NoodleofDeath check my update... 4castle is right... almost people will know what is already.... – Jordi Castilla Nov 03 '16 at 17:26
  • Made a minor modification to your java doc `Serializable#serialVersionUID`. – rolling_codes Nov 03 '16 at 17:59
  • The `@see Serializable#serialVersionUID` makes doclint choke. The reason is simple: there is no field called `serialVersionUID` in the `Serializable` interface. I think that a simple `@see Serializable` would do it. CC @NoodleOfDeath – Victor Stafusa - BozoNaCadeia Aug 31 '18 at 00:19