CS I - Lab Style Guide

The way you present your program is just as important as having a correct program. While having good comments, good variable names, and good uses of white space will not affect the correctness of your program, it will make it easier to read your program. It is important that others be able to understand your code so that they can modify your code if they have to. Half of your lab grade will be determined by your programming style.

This is a guide to help you better understand what we are looking for when we look at your labs. As the semester progresses there will be steeper penalties for styling mistakes. So, get into the habit of writing good labs from the beginning. After writing your lab be sure to look over your code and your style.

Commenting

Comments are extremely important. Take some care to write accurate yet concise comments.

You should write comments for:

  1. Class (Program): At the top of each class, you should write your name, date of creation, and a brief description of what the class is for.
  2. If you decide to do more than the assignment requested, you should describe these "extra" features in the program under the class description. Sometimes it’s hard to tell a bug from a feature.

  3. Methods: Either above or below each method heading there should be a brief description of what the method does. You should also describe what each parameter means and what the return result means.
  4. If the method code is simple you do not need to comment in the method body. If the method body is complicated, you might want to add some comments to certain areas that you deem to be complicated. Be careful not to overcomment!

  5. Variables and constants: In general, variables and constants should all have comments as to what the variable is used for. For example a good comment for your variable "Line diagonal" in NoClicking would be: the slash in the prohibit sign. Occasionally several closely related variables or constants can be grouped together under the same comment.

Blank Lines

Blank lines are used to delineate different areas of the code. The instance variable declarations at the top of your program should be separated from the header of the class and the header of the first method. There should always be space between methods. It is advisable to break up long method bodies and long declarations into logical pieces. Always start a new line after the semicolon.

Names

You should always choose names that correspond with their respective functions. If the purpose of a method is to draw a rectangle, then a good name for that method is drawRect. If there is a variable of type FilledRect that is used as the post of a stop sign, then a good name would be signPost or stopSignPost.

If these FramedRects are not connected in any other way besides all of them being FramedRects they should be named different things.

By convention, constants (indicated by "final" in Java) are all capital letters (e.g., BRIDGE_TOP), classes begin with uppercase (e.g., MyClass), variable and method names begin with lowercase, using uppercase for multi-word names (e.g., myVariableName).

Format

Your program should be organized as neatly as possible. All method headers should be aligned with each other. Variables should also be aligned.

You should indent. A good heuristic is that whenever you see an open curly brace you should indent your code 3 or 5 spaces until the ending curly brace. See the example below.

The following is a guide to what your code should look like. There are variations that are acceptable, but this is a good format to follow.

// Name:
// Lab:
// Date:
// Description of Class and Extras:

public class ClassName
{
  private double firstVariable;        //comment for firstVariable

  private int secondVariable;          //comment for secondVariable

  // Some variables need really long comments that don't fit at the 
  // end of the line
  private variableN nVariable


  // comments for method
  public void methodName1(...)
  {
    code line 1;
    if (condition) {
       code line 3;
       code line 4;
    } // end if
    code line 5;
  } // end methodName1


  // comments for method
  // param1 is the first parameter
  // Returns a value ...;
  public int methodName2(type1 param1)
  {
    etc.
  } // end methodName2
} // end ClassName