CS 251: Programming Style Commenting Guides

Good commenting is concise, meaningful, and compatible with automatic documentation generation engines, such as Doxygen or Javadoc. Good commenting makes reusable code more maintainable by making the code easier to read for developres who maintain and extend it over time. Good commenting involves documenting the head of every method, in-line comments beside single statements whose purpose may be non-obvious, a block of comments before a loop whose operation may be non-obvious or obscure, etc. In short, good commenting--combined with good programming style--makes code easier to read and understand.

The following are the guidelines for commenting programming in CS 251:

In my experience, there is a strong correlation between efficient, elegant code and well-commented, well-structured, and maintainable code. Writing readable code with effective comments is therefore vitally important.

Back to CS 251 home page.