7.5. Style and Documentation¶
7.5.1. Review Checklist¶
While style has been mentioned in assignments and modules so far, this checklist should help you keep matters of style in mind when reviewing code before submitting.
Generally we should avoid the following:
7.5.1.1. Naming¶
Names that do not adhere to proper conventions
Names that do not adequately capture and communicate the concept they represent or the purpose of the class, method, variable, or concept they represent
Names that are too long or short and not sufficiently descriptive, i.e. poor identifiers (for example single~characters, or ambiguous abbreviations, initials, acronyms)
7.5.1.2. Formatting and Indentation¶
Inconsistent/missing indentation
Insufficient white space
Commented-out lines of code
Debug statements left within the code
Multiple instructions per line or statements that are too long
7.5.1.3. Documentation and Commenting¶
Missing/insufficient class description Missing/insufficient field comments Missing/insufficient method comments Missing/incomplete JavaDoc tags Missing/incomplete args description Wrong/Misleading comments Extraneous comments or comments no more descriptive than code
7.5.1.4. Other matters of style¶
Using hard-coded values
Missing or inappropriate access modifiers
Unnecessary or unused fields/variables
