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 *.h files. This is absolutely critical. Don't leave even a single 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 *.h 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. It's fine if you 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.

Back to CS 291 home page.