I'm doing a code-review on someone's code for class.

The class is about 800 lines long, contains a good dozen of functions but the description is like 1 line long.

I'm wondering, generally speaking, how long should the description of a class be? (in Java)?


Long enough to adequately document the class.

According to Oracle, adequate class documentation includes:

  • Executive summary - A precise and concise description for the object.
  • State Information - Specify the state information associated with the object, described in a manner that decouples the states from the operations that may query or change these states.
  • OS/Hardware Dependencies - Specify any reliance on the underlying operating system or hardware. See example.
  • Allowed Implementation Variances - Specify how any aspect of this object that may vary by implementation.
  • Security Constraints - If the object has any security constraints or restrictions, an overview of those constraints and restrictions must be provided in the class specification.

  • References to any External Specifications - These are class-level specifications written by Sun or third parties beyond those generated by Javadoc.

  • 1
    +1 for first sentence. Long enough to adequately document the class. Shouldn't be any set arbitrary length for documentation or else you'll wind up with stupid filler for a lot of things. Nov 26 '12 at 4:18
  • 1
    I disagree with everything but the first sentence. There shouldn't be arbitrary fields that have to be filled. The problem with documentation requirements such as the cited one is that they encourage developers to either break the rules (and then what's the point) or to write very large classes and very large functions because of the huge documentation penalty for small classes, small functions. Nov 26 '12 at 12:41
  • I would add a small sentence for saying if the class can be safely used in a concurrent environment. It is probably part of State Information.
    – mgoeminne
    Nov 26 '12 at 14:30
  • I personally do not like JavaDoc on attribute getters/setters that do nothing beyond the obvious get/set. In fact I wish Java would make these optional and only require them if you want to override basic behavior.
    – scunliffe
    Nov 26 '12 at 18:31

The Javadoc for each method should explain why that method is in the class; what it achieves. The Javadoc for the class itself should explain why the class exists, including a synopsis of what it does, and a description of whatever it is that instances of that class are intended to represent.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.