CS 132 Style Guidelines
(a work in progress)

CS 132
Introduction to Computer Science II
Spring 2003

1. Do not write expressions that require intimate knowledge of Java's rules of operator precedence to be able to read correctly --- use parentheses to make the meaning of arithmetic expressions obvious.
   
   
2. In general, you are expected to use named constants instead of literal values in your code.
   • These named constants should have descriptive names, written in all-capital-letters, using underscores as needed to improve readability.
   • Declare such named constants using Java keyword final to ensure that they are indeed never changed;
   • and, since one generally will want only one copy of such constants for an entire class (and may even want to use them even if no objects of that class currently exist), declare such named constants using Java keyword static as well.
   • (for example,

     static final double INCHES_PER_METER = 39.37;
     

3. Every function (and many methods) are expected to be preceded by at least a PURPOSE STATEMENT using the following format:

   /* Purpose: write purpose of function/method here, using parameter names
               as appropriate for clarity
    --------------------------------------------------------------------------*/
   

4. Each function/non-constructor or non-simple-accessor method that you write is expected to have a corresponding testing function/method, whose name is the name of the function/method followed by Test and which uses the functions testHeader(), expected(), and actual() as discussed in class and in the readings to test that function appropriately.
   
   For a function, the test function should follow the function; for a method that is part of a class, the corresponding test method can go in the test class for that class.
   
   This testing function/method should be preceded by at least:

   /*  Examples/Tests:
    ----------------------------------------------------------------------*/
   

   ...or...

   /*-----------------------------------------------------------------------
    Test method for methodName()
    -----------------------------------------------------------------------*/
   

   ...although you may add to this if you wish.
   
   
5. (from TeachJava readings) "Redefine (override) the toString() method for every class that is used to represent data."
   
   
6. Java case/capitalization guidelines (quoted from TeachJava readings, section 1.3.8)
   • "By convention, Java programs are written entirely in lower case characters with three exceptions.
     • The first letter of class names are capitalized to distinguish class names from member names.
     • The names of constant static final fields are written entirely capital letters [as is already implied by guideline #2 above]....
     • The first letter in each word of a multi-word identifier after the first is capitalized. For example, the built-in Java class Object includes a method called toString() .... The capital S signifies the beginning of a word within the multi-word name toString().
     • .... A related convention is to never use the special character $ in a name; this character is reserved for the use of the Java compiler."
   
   
7. Thou shalt name new exception classes so that their names end with "Exception" --- that is, MyNewException, CustomizedSpecialException, etc.