CS206 Code Formatting Standards and Guidelines

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.
• Variable, instance variables, and function names in should be written in camelCase, starting with a lower-case letter and putting the first letter of subsequent words in uppercase.
• Constants are written in ALL_CAPS with underscore separating words.

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 method. These are like paragraph breaks in English writing.
• After every {, indent by at least 2 spaces until the matching }.
• Separate an operator from its operands by spaces. For example x = y + 3;
• In general whitespace is valuable and useful. However, do not overuse it

Line Length

All lines should have length at most 100 characters. This makes it easier to read code on a potentially small screen. If you need to break a line in order to satisfy this, the rest of the line should be indented more than its current block. In cases where the line length is within a pair of parentheses, one good option is to indent the rest of the line to match with the opening parenthesis. For example:

  if (here is a long condition for an if statement and
      the rest of the condition) {
    here is a long statement inside the if statement and
      the rest of the statement below it;
  }

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:

• Your name
• A description of the contents of the file

For example:

  /* Name:    Geoffrey Towell
   * Desc:
   *    The main driver program for Assignment 1.
   *    This program reads the file specified by 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.
   * Modified: Sep 2, 2019
   * Modified: Jan 7, 2020
   */
  

Variable comments

All global variables must be commented. Most local variables should be commented, too. If variable names are well chosen (and they should be), then these comments can be very brief. In general, consider carefully your need for instance variables and try to minimize their use.

      /**
        * Holds the number of lines
        **/
      int lineCount;
      

Function comments

All functions must be commented. The comments should explain what the method does, what its parameters are (not just their types!), and what it returns. You should use the javadoc method comment style (shown below), which lists and comments all parameters, return values and exceptions thrown.

A single group of exceptions exist for the previous statement. Namely methods that are merely get/set accessors for instance variables do not require comments. Simple twiddles on this doe not require comments, either. For example, an incrementAndGet method for an integer variable would not require a comment. If a method is more than one line long, it probably needs to be commented. It is not always the case that single line methods need not be commented. In general, if you ask yourself the question, "Does this method need a comment", then the answer is almost always yes.

/* Compute the sum of two integers
 * @param x The first integer
 * @param y The second integer
 * @return int The sum of x+y
 */
 int sum(int x, int y)

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:
starSides = 5; // set starSides to 5

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

Well-structured code will be broken into logical sections that each 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
for (int i = 0; i < n; 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:     ...
                                            }