Revision history:
Version 4.1, 2010 Sep. 15. Standards now apply to Labs 2 and later.
Version 4, 2008 Aug. 25. Minor edit.
Version 3, 2007 Oct. 3
Version 2, 2007 August 30.

C243 Coding Standards

Software is written for two audiences: the machine which will run it, and the future programmers who will revise it. The purpose of programming style is to make programs understood as easily as possible by human readers.

Textbook Standards

The standards listed here follow the book Data Structures and Algorithms in Java, by Peter Drake, Appendix section A.10, with some exceptions as noted (*).

  1. Names of constants should be all capital letters, with underscores to separate the parts (SCREEN_WIDTH).
  2. Names of classes should be written in CamelCase: all words are capitalized, with no spaces, underscores, or other separators (BeetleGame).
  3. Names of fields, methods, and variables should begin with a lower-case letter and otherwise in camel case (bestBug).
  4. Identifiers (names of constants, classes, fields, methods, and variables) should be meaningful but reasonably short, except for common conventions such as i, j, k for loop counters and x, y, z as arguments of abstract mathematical functions.
  5. (*) It is not necessary to use curly braces around a single statement body or branch of an if, while, do/while, or for statement.
  6. Always indent code according to its structure. In particular, the "body" of anything, whether a control structure or a class or a method, should be indented.
  7. (*) A javadoc comment is required at the beginning of each public or protected class, interface, field, constructor, and method, except:
    1. Methods defined in a class in order to implement an interface, or overriding methods of a superclass (this includes the toString method, which overrides a method of the Object class);
    2. Trivial methods, including simple accessors and mutators.
    The javadoc comment should be placed just above the beginning of the class, method, or other component. For example: 
    /** A Beetle has various body parts used in the Beetle game.  */
public class Beetle { 
  ...
}
  8. The components of a class or interface should appear in this order:
    1. Constants (static fields)
    2. Instance variables (non-static fields)
    3. Constructors
    4. Other methods besides main
    5. main method

Additional Standards

(Added in version 3, applicable to Labs 2 and later.)

  1. Begin each source file with a header comment that states the file name, the author's name and email address, course, date, and a brief description of what's in the file.

    Example:

    // File:    Hello.java
// Author:  Jean G. Nyuss (jgnyuss@hoosier-state.example.com)
// Course:  C243
// Date:    January 1, 2010
//
// Purpose: This program prints the message "Hello, Java!"
  2. Avoid lines which are so long that they "wrap around" when printed. A line of code should be no wider than the printed page—that is, 80 characters wide.

    Split complex statements across lines at sensible breaking points, and indent the continuation lines an extra level.

  3. Most methods should be short. If a method is getting too complex, divide it into subproblems, and define a helping method for each of the subproblems. Generally, several short methods are better than a single long method.
  4. Use methods to avoid code repetition. It is hard to give strict rules about this, but here are some rules of thumb:
    1. One complex line repeated two or more times.
    2. Two or more simple lines repeated two or more times.
    Loops can also be used (sometimes) to avoid repeated lines code.
  5. Use methods to improve code clarity. Sometimes the meaning of a few lines, or even one line, of code can be made clearer by wrapping it in a method definition and giving it a name. This may be true even if the lines are unrepeated.
  6. Use a comment to document each variable if the variable name is not totally self-explanatory.
  7. Avoid obscurity. Take a straightforward approach rather than using clever tricks that may be hard to understand.
  8. Wherever the code is not self-explanatory, add comments to explain what is going on.
  9. Avoid using the break and continue statements in loops; these result in unstructured code. Use an if/else statement instead. (Use of break in a switch statement is okay: there, it can't be avoided.)
  10. Usually, error conditions should be signaled by throwing exceptions rather than returning special values like -1 or false.

    Hint: Define an exception class for each different kind error. To avoid proliferation of files, begin each class declaration with just class (i.e., package-visible) instead of public class. Each public class must be in its own file that has the same name + ".java", but you can put lots of package-visible classes in the same Java source file with any public class. For example, if you have a Queue class, you could declare queue-related exception classes in the same source file.