.. This file is part of the OpenDSA eTextbook project. See
.. http://opendsa.org for more details.
.. Copyright (c) 2012-2020 by the OpenDSA Project Contributors, and
.. distributed under an MIT open source license.

.. avmetadata::
   :author: Molly Domino


Style and Documentation
=======================


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:**


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)


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


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


Other matters of style
~~~~~~~~~~~~~~~~~~~~~~
* Using hard-coded values
* Missing or inappropriate access modifiers
* Unnecessary or unused fields/variables