7.6. Style and Documentation¶
7.6.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.6.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.6.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.6.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.6.1.4. Other matters of style¶
Using hard-coded values
Missing or inappropriate access modifiers
Unnecessary or unused fields/variables
