The following applies to all programming courses unless otherwise noted. Non-programming courses will have class specific guidelines provided by the instructor.

[ companion video ]

Purpose

These commenting standards are designed to develop professional documentation habits and consistent coding discipline. They also support the practices of the AI-Integrated Classroom. Submitted code must follow the commenting standards and required formats shown below.

Some required fields and empty sections are intentionally more explicit than typical production documentation. This is deliberate: you are required to consider parameters, returns, exceptions, notes, and class structure explicitly rather than leave it unclear whether something was considered or simply omitted.

Process

Complete examples are provided on GitHub for both Python and C/C++, and must be followed exactly. Each language example includes its own README explaining the standards, professional conventions, and deliberate instructional choices in detail.

The C/C++ examples use Doxygen-style documentation blocks. The Python examples use standard Python docstrings with reStructuredText/Sphinx-style fields. In particular, pay attention to the following:

• Every code file, unless noted otherwise, must begin with the required file/module documentation. C/C++ files use a Doxygen-style documentation block; Python files use a module docstring.
• Every function/method must use the required documentation format. In C/C++, the documentation block is placed immediately above the function definition. In Python, the docstring is the first statement inside the function or method.
• Note that main() is a function and requires standard function documentation.
• Required documentation fields must always be present, even when a category does not apply. Use the exact none, None, or void form shown in the language-specific examples.
• Class header files (C++) are required to be documented exactly as shown in the examples. Required class sections must remain present even when empty and should be marked none exactly as shown.
• Do not add, remove, or rearrange fields within the required documentation standards. Additional explanatory comments outside the required documentation are permitted only when they add useful information.
• Do not change the required documentation format. This includes field structure, spacing, and, for C/C++, the documentation-block star pattern.

General Commenting Standards and Debug Statements

• Do not leave any of the following in your code:
  • Debug statements.
  • Commented-out code.
  • Trivial comments.
  • Excessive comments.
• Commenting in addition to the required standards is allowed in the following cases:
  • To explain something that is not obvious.
  • To explain a non-standard approach or solution to a problem.
  • For grading purposes, if you have a comment or question directed at the instructor.