CS 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 people who have to come along and extend it 5 or 10 years down the road. Good commenting is a comment at the head of every single function, 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. Good commenting makes code easier to read and understand.

The following are the guidelines for commenting programming in my CS classes:

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 291 home page.