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. You should always use good naming conventions for your variables and methods, but this is not a substitute for good comments, although some would argue that it is.  I have seen code in which the code itself can explain what is happening, but not why. I have also observed that if you can explain what you're doing in English, you probably understand it well enough to explain it to the computer.

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.   For example:

  Written by John Cole for CS6326.001, assignment 4, starting April 1, 2017.
    NetID: jxc064000

2. Every method must have a comment above it that describes what the method does, and usually its inputs and outputs. The exception is tiny functions of a few lines where the name adequately describes the functionality and the return value, if any, is obvious.  Get and Set methods fall into this category.

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. Some of your variables will need a comment next to them that explain what they signify and other useful information. However, good variable naming conventions (see next item) can make this less necessary.

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".  I know most development environments have a way to find variables and not just text, but I don't always rely upon that.  In any case, i and j are seldom good variable names.  If you're working with the rows and columns of a matrix, for example, why not use iRow and iCol?

6. When I was teaching 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.

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 with its return value and parameters first. Then write the comments describing how the method works. Finally, write the method itself.

8. I mention above that your comments should explain why you're doing certain things.  Here are some examples of why you should do that.  In one of my programs I had code to clear a buffer to blanks, and the comment said that this was so.  However, it failed to explain that this was being done because characters could be placed at random positions in the buffer, which you can think of as a simple array.  The fact that this could happen required domain knowledge and was not obvious from a cursory examination of the code.  In another program, it was clear that I was putting various information, such as the position in a list and the name of the last thing found in that list, on a stack.  The reason was that the program was emulating recursion in an iterative loop, and this was not at all obvious from the code.

Here are sample header comments from one of my programs.  You don't need to enclose everything in asterisks; that is simply my style.  However, you should have that level of detail about the program operation.  Someone reading the comments from this program could easily figure out how to use it.

/******************************************************************************
* Attendance Tracking Program.
*
* This program tracks class attendance. It operates in two modes: First, it
* will look up an ID scanned from a Comet card and enter attendance for that
* person. Second, you can edit attendance for any student and date, although
* this is probably better done in Excel.
*
* If the ID is not in the system, you can enter the NetID and the program will
* enter the card ID and attendance for the appropriate date. You can also
* click on a blank Card ID for a student and the program will fill in the
* current ID.
*
* You must have a file called Classes.txt in the same directory as the
* program. This contains the fully-qualified path and file names of Excel
* workbooks (.xlsx files) that are your attendance roster. When the program
* opens, you'll be able to pick one of these for taking attendance.
*
* The workbook must contain a worksheet called Attend. Columns on the
* spreadsheet are in the order downloaded from Coursebook, using only the
* following:
* Card ID -- Not from Coursebook; you'll have to add
* NetID
* First name
* Middle name
* Last name
*
* The program will create new attendance columns with the current date when
* you press the New button. An attendance column can have four possible values:
* blank -- person was absent.
* Y -- Person was present.
* L -- Person was present but more than 10 minutes late.  The program does
* not currently check the time.
* X -- Excused absence.
*
* Written by John Cole (jxc064000) at The University of Texas at Dallas
* starting August 18, 2016.
******************************************************************************/

Here are the comments over a function:

/**************************************************************************
 * Load all students from the appropriate sheet into a list of Student
 * objects. The list is an instance variable.
 **************************************************************************/
private void loadStudents()
{}

Back to John Cole's main pageBack to Notes for Students page.