Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

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

share|improve this question
add comment

2 Answers 2

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.

share|improve this answer
    
+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. –  cspray 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. –  David Hammen 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
add comment

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.

share|improve this answer
add comment

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

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