Documentation Standards for Prof. Cole's Classes

Part of your program grade is dependent upon documentation, that is, the comments in your program. After going through well over a thousand programs in my last few years at UTD, it occurs to me that I was making a bad assumption: that most students have been taught what constitutes good comments in a program. Therefore, below is what I consider to be a standard for your programs. If you follow these guidelines well, you will get full points for that aspect of your assignment.

1. Every module must have a block of comments at the beginning that contains the following information: Your name, your Net ID, the date on which you started writing the program, and your purpose in writing it. The purpose will generally be because it is an assignment for a particular class, and you should name the class and section here. This header must also include a general description of what the program or module does.

2. Every method must have a comment above it that describes what the method does, and usually its inputs and outputs.

3. Major sections of code within a method must have comments explaining what they do. The beginnings of loops and conditionals are good places for this. Blocks that set up databases, initialize objects, and the like are also good places for a block of explanatory comments. The best comments describe what you're doing, and they also describe why you're doing it.

4. Many of your variables will need a comment next to them that explain what they signify and other useful information.

5. Follow good naming conventions. Even temporary variables such as loop counters should have names that mean something and can be found using the text search. For example, you will never see this in my code: for (i=0; i<10; i++). Instead I'll use, at a minimum, something like this: for (ix=0; ix<10; ix++) because I can find the variable "ix".

6. When I was at IIT I based part of the grade on the grammar and spelling in the comments. However, given the large population of students for whom English is not their first language, I no longer do this. Please do your best to be clear and correct.

7. Don't write the code figuring you'll go back and document it later. Write the description before you write the code. For example, if you decide you need a method to, say, return an average price for a set of items in a database, define the method and its return value and parameters first. Then write the comments describing how the method works. Finally, write the method itself.