University of Akron Computer Science Documentation Standards

The following program standards are to be followed by all programmers.

1. Each program should include the following comment at the beginning of the file. Use the "keywords" at the left to identify sections of this documentation block. Customize the sections in italics.
   

2. // PROGRAM	program name and/or brief title
   // PROGRAMMER	programmer's name
   //
   // SIGNATURE    _____(Your signature on the submitted hard copy)
   //     
   //  - I have not used source code obtained from another student,
   //    or any other unauthorized source, either modified or unmodified. 
   //     
   //  - All source code and documentation used in my program
   //    is either my original work, or was derived, by me, from the source
   //    code published in the textbook for this course or presented in class.
   //     
   //  - I have not discussed coding details about this project with anyone
   //    other than my instructor. I understand that I may discuss the
   //    concepts of this program with other students, and that another
   //    student may help me debug my program so long as neither of us
   //    writes anything during the discussion or modifies any computer
   //    file during the discussion.  I have violated neither the spirit
   //    nor letter of this restriction.
   //
   // DESCRIPTION	brief description of the program and its purpose
   // EXTERNAL FILES: 
   // INPUT	description of expected input files or devices
   // OUTPUT	description of expected output files or devices
   // WARNINGS	limitations and usage
   // SYSTEM	Microsoft Visual C++ 6.0/Windows 2000
   // DATE	date of creation
   // MODIFICATION date of modification, programmer (lines added as needed)
   //	description of modifications
   

3. Use both upper and lower case characters where appropriate. (Reserved words and preprocessor keywords must be written in lowercase.) Documentation should in general employ proper grammatical structures.
   
4. The words of a compound identifier are to be separated by underscores or the use of uppercase letters. For example: first_number, Last_one, AverageScore, oneExampleInteger. You should choose one style and be consistent! Descriptive identifier names are required. Variable declarations should be followed by documentation describing its meaning and purpose. Example: int My_Age; //my age on the day the program is being run
   
5. Watch your line lengths! Be sure that your programs can be printed without line wrap due to printer margins.
   
6. Normally, each C++ statement in your program should begin on a separate line of your program. Use blank lines to visually separate sections of your program. Use indentation consistently to improve readability. Consult example programs in the text for indentation and spacing guidelines.
   
7. Programs should be separated into functions and program units according to functionality. Avoid excessively large blocks and files. Note: some people consider a function with more than 10-20 statements to be excessively large! Each function should accomplish a single, well-defined task at a suitable level of detail.
   
8. Introduce each function with a comment block that includes a description of its purpose. Include specifications for all parameters (what is expected to be true when the function is called and when the function is done) and describe any side effects. Be sure to document limitations of each function (for example, cases it is not designed to handle). Comment on the implementation details when it will clarify how the task is being accomplished.
   
9. Declare variables at appropriate locations. Major variables should be at the top of each function. In some cases, local variables whose use is limited to a nested block should be declared inside the block or just above it. Notice that this disallows the use of global variables.
   
10. Use named constants (all upper case) to represent literals (numeric and character constants) in your program unless they are 'self-identifying.'
    
11. Only related variables should be defined in a single line. Supply comments indicating the intent of the variable. For example: int max_gr, min_gr; //max and min grades allowed
    
12. goto, continue, and break (with the exception of inside a switch statement) must be used with extreme care. Ample documentation justifying such violations of structured programming guidelines must be included. Hint: do not use these!
    
13. Avoid complex and cryptic statements, especially those involving pre- and post-increment operators. For example, x = ++y; or z++ * --z; should be avoided. The second expression is actually undefined and should not be used under any circumstances!
    
14. Avoid nesting statements too deeply (with the possible exception of nested if/else statement used to implement a multi-way selection structure). Follow the text's suggestions for indenting this structure.
    
15. If you find a null statement to be appropriate in your program, include a comment indicating that it was intentional!
    
16. Position comments within the body of a program so that they do not interfere with and cannot be confused with the actual code. Avoid useless comments. For example: int i = 0; //Initialize i to 0. It would be better to comment this with //Initialize counter to start at beginning of list

Thanks to Dr. Pelz for originally compiling this list.