Coding Standards

 

  1. Comments
    1. Start all programs with a comment block. Use Javadoc style comment blocks (i.e., begin with /** and end with */). At a minimum, include the following information:

                                          i.    A brief description of what your class/program does.

                                        ii.    Your name

                                       iii.    The date

                                       iv.    Class and section number

                                        v.    Assignment/Project number or name

                                       vi.    Example:

/**
 * This is an example comment block. Program
 * description goes here.
 *
 * Name: Mike Jochen
 * Date: 12/31/99
 * CPSC 123 A456
 * Project 1
 **/

    1. Describe every method with a comment block placed immediately before the method. Again, use Javadoc style comment blocks. The comment should give a brief description of the method, including input and output.
    2. Inside each method, use comments to describe what you are doing at major sections.
    3. You can use comments to further describe variables, but start with a good variable name!
    4. Don’t go overboard with comments. Use them in places where you need to describe what is happening in your program, or to separate major sections of code. Do not comment every line of source code!

  1. Class names
    1. Use a name that describes your class.
    2. Start class names with an upper-case letter.
    3. Class names should be a noun (e.g., car, person, book, factory, etc.)
    4. If using more than one word as a class name, run the words together and capitalize the first letter of each word.

Example: CarFactory (note: this is often referred to as camel notation.)

  1. Method names
    1. Use a name that describes what your method does.
    2. Start method names with a lower-case letter.
    3. If using more than on word as a method name, run the words together and capitalize the first letter of each word after the first. Example: wordSort.



  2. Variable names
    1. Use a name that describes you variable – what information it holds.
    2. Start variable names with a lower-case letter.
    3. If using more than on word as a variable name, run the words together and capitalize the first letter of each word after the first. Example: radiusInput.

  3. Constants
    1. Don’t use “magic numbers” in your program (i.e., a value that just appears in your source code). If you need to use a constant value, declare a constant and use the constant name instead of the value.
      Example:       public final double PI = 3.14159
    2. Use descriptive names for all constant values
    3. Names for constant values should be in all capitals.
    4. Use underscores to separate words in constants.
      Example:       public final double PAY_RATE = 10.75

  4. Indent
    1. Indent each nested block of code.
    2. The specific amount of indent is not as important as being consistent. A common amount of indent is 4 spaces. Most IDEs/editors have configured the tab key as a good indent amount (or will indent automatically for you!). Use the same indent amount for each nested block of code!
    3. Example:

      if ( x < 10) {

          System.out.println(“X is too small”);
          if (x < 0) {

              System.out.println(“X is REALLY too small”);
              x = 10 * y;

          }

      } else {

          System.out.println(“X is just right.”);

      }
  5. Performance tricks versus readable code
    1. We all love to make our code as efficient as possible, trying to optimize for space, or speed, or some other metric. However, writing optimized code often makes for  code that is more difficult to understand (performance optimization and program comprehension are usually conflicting goals)
    2. In this class, program comprehension wins out over the use of arcane language constructs or other features that may allow you to do more things in less time or space.

  6. Brace placement
    1. Be consistent in how/where you place your braces around blocks of code
    2. One common scheme is to place braces at the end of the line as in the example given above.
    3. Another scheme is to place braces on a new line, by themselves.
    4. I don’t care which scheme you use, but be consistent!

  7. The overall goal is to make sure your code is neat, READABLE, and UNDERSTANDABLE. Code that is difficult to read usually results in code that is difficult to understand. That’s when errors magically appear! Your code should be self-documenting (i.e., it should explain what it is doing inline). Anyone should be able to pick up your code and be able to understand what is going on.