CS Programming Style Commenting Guidelines

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:

Comments in your header files. This is absolutely critical. Don't leave even a single method or instance variable uncommented. If other people ever use your code in a project of theirs, the .h file is where they are going to go to learn how your code works. Uncommented methods and instance variables are the kiss of death. If you leave comments out of your header files, you will lose 3 points.
Comments at the head of methods. Good comments at the head of a method will have the method name; its purpose; and its parameters, return values, and types, along with a description of what each of these parameters and return values represent. A minimal comment at the head of a method will have a description of the method's purpose, along with a note if parameters are passed by reference for readability. If you omit comments at the head of functions in your *.i or *.cpp files you'll lose 3-5 points.
In-line comments. If you write a ridiculously-complicated one-liner, it should be commented. If you make a check whose purpose is not immediately obvious, it should be commented. If you have a block of code that's non-obvious, it should be commented (especially if there are conditional statements in the code). It's fine to address all these points in a single block comment before a loop or an implementation of an algorithm, as long as they're noted somewhere. If you don't place an in-line comment where you should have you'll lose 2-3 points.

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. Therefore, code that's not documented thoroughly will not be reviewed.

Back to CS 251 home page.