Purpose

Commenting guidelines and examples are structured to conform to professional standards as much as possible to help 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 an assigned grade of zero. The following guidelines, and classes in general, are designed to simulate real-world software engineering practice as much as possible. The purpose of this standard is to train the student in professional coding practices and to prepare them both for the workforce and advanced study.

No variations on these standards will be accepted.

In particular, note the following from the examples on GitHub:

• Every file must have a comment header, as shown in the examples.
• Do not add or remove anything from the commenting standards. Adding to the standard will receive a grade penalty no different than removing from the standard.
• Do not change the format of the commenting standards. This includes spacing and star patters.
• Function/Method comment blocks are inside the function header.
• 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." See the examples.

Complete Examples

Complete examples in both Python and C/C++ are available on GitHub. Follow the examples precisely. Your code will be expected to follow the examples given exactly. Deviation from the examples will result in a grade penalty, up to and including a zero. Also note that the example code shows proper committing, modularty, scope, and a number of other best practices in procedural and object-oriented programming.

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.

Regarding commenting for explanation:
• 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.