CS 251: Programming Style Commenting Guidelines

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:

Comments in your *.java files. This is absolutely critical. Don't leave even a single data member uncommented. If other people ever use your code in a project of theirs, the *.java files (or auto-generated documentation) will often be where they go to learn how your code works. Uncommented methods and instance variables are the kiss of death. If you leave comments out of your *.java 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 *.java 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 251 home page.