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