Code Formatting Standards

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. 

For these reasons, we will be using the following coding standards in this class.  Adherence to these standards will be a portion of your grade on each assignment.


Naming Conventions



Whitespace

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


Comments

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

/*****************************************
 * Assignment 1
 * Name:    Barbara Smith
 * E-mail: 
bsmith22@brynmawr.edu
 * Course:      CS XXX - Section 01
 * Submitted:    1/10/2013
 *
 * The main driver program for project 1.
 * 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.
 *
***********************************************/


Class Header Comments

Every class should contain a header comment that includes the following information:
For example:

/*****************************************
 * Represents a single-family residential home, including
 * all exterior features of the house, and its location.
 *
 * Author: Barbara Smith (bsmith22@brynmawr.edu)
 *
***********************************************/
class House {
   ...
}

Function Header Comments

Every function must have a header comment that includes the following:
For example:

/** Calculates the area of a circle with the specified radius
 * Parameters:
 *     radius : the radius of a circle
 * Returns the circle's area
 */
double circleArea (double radius) {
   ...
}

In-Line Comments

The basic rule of thumb is that you should be able to delete all of your code and then regenerate a working program from only the comments.
An in-line comment 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
for (i = 0; i < arrayLength; i++) {
    if (array[i] % 2 == 1) {
        array[i] = array[i] + 1;
    }
}

Endline comments should very rarely be used, and then only to explain particular aspects of a line, such as what a variable means or some pecularity:
   
int width = widestXCoord/2 % 11;  // divisor must always be a prime number

 

Indentation Styles

Choose one of the two styles and use it consistently

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:     ...
                                                     }

&amp;lt;br&amp;gt;&lt;br&gt;