Program Documentation and Style

COSC 1320 - C++ Programming and
ITSE 1307 - Introduction to C++ Programming
Bob Comer, Professor of Computer Studies

Program Documentation and Style

One of the requirements of this course is that you program in a professional programming style. 20% of your grade on each programming assignment will be based on program documentation and style. The goal is to make your program easy to read and understand. Click here for an example program with documentation.

You should follow a standard indentation style that highlights the structure of your program. I like the indentation style used in our textbook, but as long as you consistently follow a neat, professional looking style, I won't complain.
Each program must begin with a comment that includes: a) your name, b) program status - either "Complete" or describe any incomplete or non-functioning part of your program, and c) a brief 1 to 3 line description of what the program does.
In your source file, the code for the main function should come first followed by your other functions.
Each function should begin with a 1 to 3 line comment describing what the function does.
All local variables and constants should be declared at the beginning of the function block.
Use meaningful variable names. One or two character names are rarely meaningful. For example, c and ch would not be acceptable names for a variable that holds the change returned from a purchase. chng is OK. change and changeDue are even better.
Declare one variable or constant per line and include a comment to the right describing how the variable or constant is used.
If a function is longer than 4 or 5 lines, it should be divided into sections by task with blank lines between sections. Include a 1 or 2 line comment at the beginning of each section describing what the section of statements does. I want to be able to read the comment at the beginning of a section and understand what the section does without looking at the C++ code. Note: These comments should say WHAT the section does, and not necessarily HOW it does it.

Return to C++ Home Page