Purpose
Commenting guidelines are structured to conform to professional standards
as much as possible to train the student in professional
coding practices. All submitted code must conform to the following examples and guidelines exactly
Failure to do so will result in your submission being penalized, up to and including being rejected and
assigned a grade of zero.
Process
Complete examples
are provided on GitHub for both Python and C/C++, and must be followed exactly.
In particular, pay attention to the following:
- Every file must have a file comment header. This is the comment block
at the top of every code file.
- Function/Method comment blocks are required for every function/method
and must be just below the function header and above all function code.
- Note that main( ) is a function, and requires standard function commenting.
- If function/methods are missing parameters or a return, or exceptions,
you must still list them in the comment block as "none" or "na."
- Class header files (C++) are required to be commented exactly as shown
in the examples.
- Even if a comment block is empty, you must include the default comment block.
- Do not add or remove anything from the commenting standards.
Adding to the standard will receive a grade penalty no different from
removing from the standard.
- Do not change the format of the commenting standards. This includes
spacing and star patters.
General Commenting and Debug Statements
All code should be commented appropriately to professional standards.
- Do NOT leave any debug statements in your code.
Do not simply comment them out, you must remove them completely
prior to submission.
- Do NOT leave any commented out code in your files.
- Do NOT comment things that are trivial or easy to understand
(unless you need the comment for yourself for some reason in which case it's okay).
- Do NOT comment every line. Comment only where necessary.
If you were previously taught to comment every line, that is a teaching technique, and not part
of professional coding standards.
- DO comment anything that needs explaining and/or is unusual.
- DO comment wherever you want to convey
information for grading purposes. For example, you couldn't get something quite right,
but you understand how it was supposed to work, explain your thought
process in a comment. This will likely result in a higher grade if
it is obvious you understand what should have been done and you were trying to do it.