Code Formatting Standards and Guidelines

All organizations and companies have specific conventions for formatting code. While these formatting rules may vary from place to place, they are essential for making your code readable and for enabling others to understand, use, and modify your code in the future.

Naming Conventions

• Use meaningful names! For example, if your program needs a variable to represent the radius of a circle, call it radius, not r and not rad.
• Use single letter variables for simple loop indices only.
• The use of very obvious, common, meaningful abbreviations is permitted. For example, “number” can be abbreviated as “num” as in numStudents.
• Begin variable and function names with lowercase letters.
• Begin class names with uppercase letters.
• Use all uppercase for symbolic constants (e.g., public final double PI = 3.14;)
• Prefix global variables with g_ and member variables with m_.
• Separate words within identifiers with mixed upper and lowercase. For example:
  • Variables: grandTotal, circleRadius
  • Functions: computeArea, saveFile
  • Classes: CircleTable, PieChart
  • Globals: g_numWords, g_puppyImage

Whitespace

The most-readable programs are written with prudent use of whitespace (including both blank lines and spaces).

• Use blank lines to separate major parts of a source file or function.
• Separate declarations from executable statements with a blank line.
• File and class header comments begin in the first column, with all function definitions indented one column to the right.
• All statements in the body of a function are indented beyond the function definition. Statements inside of a loop or part of an if structure are indented further.

File Header Comments

Every source code file should contain a header comment that describes the contents of the file and other pertinent information. It must include the following information:

• The assignment number
• Your name
• Your school e-mail address
• The class and section number
• The date the assignment was submitted
• A description of the contents of the file

For example:

/*****************************************
 * Assignment 4
 * Name:    Barbara Smith
 * E-mail:  bsmith22@brynmawr.edu
 * Course:      CS 110 - Section 01
 * Submitted:   10/2/16
 *
 * The main driver program for project 4.
 *
 * This program reads the file specified as the first command line
 * argument, counts the number of words, spaces, and characters and
 * displays the results in the format specified in the project description.
 *
 *****************************************/

In-Line Comments

You should strive for your code to be self-explanatory. However, it is inevitable that some lines of code are more intricate. In these cases, a comment describing the code is well-advised. The comment should not simply translate the code to English, but should explain what’s really going on. For example:

// Unhelpful comment:
g_starSides = 5; // set g_starSides to 5

// Helpful comment:
g_starSides = 5; // reset g_starSides to original value

Well-structured code will be broken into logical sections that perform a simple task. Each of these sections of code (typically starting with an if statement or a loop) should be documented.

An in-line comment too long to appear to the right of your code appears above the code to which it applies and is indented to the same level as the code. For example:

// increment all the odd values in the array
int arrayLength = array.length;
for (i = 0; i < arrayLength; i++) {
    // add 1 only to the odd values
    if (array[i] % 2 == 1) {
        array[i] = array[i] + 1;
    }
}

Indentation Styles

Choose one of the two styles and use it consistently (note how the braces are placed):

if (condition) {                            if (condition)
    ...                                     {                    
} else if (condition) {                         ...
    ...                                     }
} else {                                    else if (condition)
    ...                                     {
}                                               ...
                                            }
                                            else
                                            {
                                                ...
                                            }


for (loop control expressions) {            for (loop control expressions)
    ...                                     {
}                                               ...
                                            }


while (condition) {                         while (condition)
   ...                                      {
}                                               ...
                                            }


do {                                        do
   ...                                      {
} while (condition);                            ...
                                            } while (condition);
                                           

switch (variable) {                         switch (variable)
   case constant1:   ...                    {
        break;                                  case constant1:   ...
   case constant2:   ...                             break;
        break;                                  case constant2:   ...
   case default:     ...                             break;
}                                               case default:     ...
                                            }