CMPSC 101 & 201 Coding Standards

Study this program or practically any of the demo programs which adhere to the Coding Standards

When a programmer works or studies in an institution, he or she must work closely with others. Often, programmers work on team assignments. Therefore, the code that one programmer writes must be consistent with the code written by others around him or her. Following the institution's coding standards is essential. Therefore you must follow these guidelines for every program assignment even if examples in the textbook or from the lecture notes are not consistent.

  1. Type blank spaces around operators of all kinds. Blank spaces should be used to improve the readability of the program. Always surround binary operators such as assignment operator, plus symbols, etc. with blank spaces.

    Example:

          Instead of    

    cout<<sum=amount+sum<<endl;
       
            use   

    cout << sum = amount + sum << endl;

  2. Use consistent and conventional levels of indentation, especially with regard to complex structures like if statements, loops, switch statements, etc.

  3. Line up inline comments when they appear to the right of executable code.

  4. Add blank lines above and below structures such as loops, if statements, switch statements, and functions.

  5. Tabs and spacing should be used to separate the program into logical and functional parts.

  6. If your program uses functions include function prototypes above the main function and place the function definitions themselves below the main function.

  7. Declare variables at the beginning of the function in which they are used. However, you may declare the loop variable in a for loop within the loop's initialization expression.

  8. Use perfect grammar throughout your code, especially when it can be viewed by a user. You should use punctuation as well, where appropriate.

  9. Make sure that spelling is perfect in all code that you submit. If you have to copy and paste your code into a word processor, like MS Word, and run a spell-check before you submit your program.

  10. When you obtain user input, make sure that the input cursor stays on the same line as the output prompt (if possible and when appropriate.) It is best to use a colon (:) and a space to separate the input prompt from the user's actual input.

  11. The return type for the main function should be expressly set to int, even though int is the default return type. Make sure that zero is the value that is returned by the main function, too. The parentheses after the keyword, main, are technically optional in Visual C++, but should be used anyway. So you must use the main function header:

    int main( )

    and the statement

    return 0;

    should be the last statement in the main function.

  12. One-line if statements are not allowed. Also, the body of an if statement or each of its else if or else clauses must be placed in curly braces. The opening curly brace must be placed on the line below the keyword if and its control expression. For example,

    if (num > 0)
    {
       cout << num << " is greater than zero" << endl;
    }

    is proper. The following if statements do not follow these Coding Standards:

    if (num > 0) cout << num << " is greater than zero" << endl;

    or

    if (num > 0)
        cout << num << " is greater than zero" << endl;

    or

    if (num > 0) {
       cout << num << " is greater than zero" << endl;
    }

    or

    if (num > 0)
    { cout << num << " is greater than zero" << endl; }


  13. Curly braces must be used to bracket the bodies of for, while, and do/while loops, even loops with only one body statement. The opening curly brace must be placed on the line after the loop's keyword and the closing curly brace should be placed on its own line of code except for do/while loops. Follow these samples for proper style:

    for (i = 0; i < 10; i++)
    {
       cout << i << endl;
    }

    while (num < 10)
    {
       num++;
       cout << num << endl;
    }

    do
    {
       num++;
       cout << num << endl;
    } while (num < 10);

  14. Use Courier or New Courier font for all printed source code.

    Print your program from within the Visual C++ software. To avoid formatting mistakes, do not print your program from Angel or Microsoft Word.
  15. Do not add extra prompt messages asking the user if he would like to continue or exit a program if it is not specifically called for in the program specifications. For example, if the program specs only call for allowing the user to type one input then do not prompt the user asking if he'd like to type a second input. Also, do not use a clear screen command ( such as    system("CLS");    ) to clear the screen at any point during your program's execution.
  16. Be sure to add the

    system("PAUSE");      

    statement just before the main function's return 0; statement as in:


       system("PAUSE");
       return 0;
    }// end of main

    CMPSC 201 students must add #include <cstdlib> at the top of their programs in order for this to work.


Documentation Standards

All students must apply these principles to every program that is submitted for a grade. Even though a program may function properly, the programmer is responsible for documenting the program. Programming assignments will lose points if they do not follow good documentation principles.

1. Program header - Each program or procedure should have a header block of comments with the following comments:

// [Your name]
// CMPSC 101
// [The name of the source file here]
// [The date]
// Purpose - [Describe the assignment (specs) of the program assignment in complete sentences. If
//                 necessary continue in multiple lines of code, indenting for readability.]

2. Signpost Comments - If the module contains several major steps or functional parts, there should be comments (called signpost comments) explaining the function of each major part.

3. Inline Comments - If a specific line or section of code is not self-explanatory, you must include an inline comment explaining the purpose of that line.  Do not necessarily assume that fellow programmers (or teachers) will understand your logic. In general it is better to "overdocument" than to "underdocument" but do not document the obvious.

4. Variable Dictionary - A description of the purpose of each variable. This should be done with an inline comment on the line with the declaration of that variable. While this may take more room, it definitely enhances the readability of the program. This set of variable descriptions is sometimes called a variable dictionary. Do not declare multiple variables on the same line of code even though C++ allows this syntactically.

For example, the inline comments in the right margin serve as a variable dictionary. The purpose of each variable is explained. These comments must be lined up vertically.

int apples = 0; 
double costApples = 0.0;
int i = 0;
const double PRICE_PER_APPLE = 0.50;
 // number of apples purchased
// cost of apples purchased
// loop variable
// price per apple

 





Do NOT include comments such as:

int apples = 0;       // declaring apples as an integer and initializing it to zero

This comment states the obvious plus it does not explain the purpose of the variable apples. In fact, do not use any of the words "declare", "declaring", or "variable" in your comment.

5. Input and output prompts - Assume that the user is a "knucklehead". Certainly, the user cannot be expected to know anything about the computer programming language that you happen to be using. In fact, you should assume that the user knows little about computers in general. Therefore, you must always prompt the user with a clearly worded message to indicated EXACTLY what kind of input you expect him/her to enter. This prompt should be formatted nicely as well and it should be written with proper grammar. Likewise, you must include descriptive output prompts or messages with ALL output so that the user knows what each value represents. Note that input and output prompts are considered to be external documentation, not internal documentation.

6. Consistency - Use a consistent format with regard to internal documentation. If you use complete sentences in inline comments, then do so throughout your program's code, otherwise use explanatory, understandable phrases. Always use consistent indentation that improves the readability of the program. Each level of indentation must be either 2, 3 , or 4 spaces. You must be consistent. The indentation pattern must be consistently applied within the program. You must indent the body statements within ALL loops. You must indent each branch of a decision structure (eg. if/then statements). Inline comments, where used, must be aligned with each other as practically as possible. Variable declarations must be one per line and aligned consistently. Statements which are continued on a second line must be indented significantly (more than the normal indentation).

7. Identifiers - Identifiers (variable names, function names, etc.) must be self-documenting.  That is, they should be whole words or phrases that are meaningful and descriptive as to the purpose of the variable or function that they represent. In this course, identifiers must begin with a lowercase letter and successive words must be capitalized for readability. For example, numPassingStudents would correctly serve as a variable name for a variable that stores the number of students who pass this course. On the other hand, num_passing_students should not be used even though it is syntactically correct and would not cause a compiler error. Constant identifiers must be uppercase letters with the underscore operator used to separate multiple words. For example, PA_SALES_TAX_RATE would serve as a good constant identifier.

8. Include an inline comment after the closing brace of each function to mark the end of that function. For example, you should always document the closing brace of the main function like this,

} // end of main

 If you have a function named round, then you should include a comment such as

} // end of round