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.
4
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.