Java Style Guidelines for CMSC 132 projects

1. Identifiers
   

   For classes, interfaces, and enumerations, use upper camel case:

   • Dog
   • DogFood
   • DogFoodBowl

   For variables and methods, use lower camel case:

   • eat
   • eatFood
   • eatFoodBowl

   There is a separate style for "symbolic constants" -- see below.

   Be sure to use English words for names of identifiers. You may use a small degree of abbreviation, but don't abbreviate too far. Also, please don't create identifiers that are absurdly long.

   These are OK:

   • currentItem
   • currItem

   These are NOT OK:

   • crIt
   • currentItemBeingProcessedAtThisPointInTime
   • temp
   • v
   • r4

   You may occasionally use single letter variables names (x, y, i, j) in certain contexts. For example, when process x and y coordinates, it would be appropriate to use x and y. For loops, try to use something better than i or j, if you can. Many times a for-each loop eliminates the need to use i or j. With a traditional for loop, it's better to use something like row, col, or even index.

2. Braces and Indentation
   

   We are going to be quite fussy about this! There is only ONE style that we will accept. See examples below (and non-examples subsequently).

   These are the correct style. Note that we require the braces, even in cases where the block consists of a single statement.

   • if (value < 4) {
         System.out.println("Hi");
     }
                     

   • if (value < 4) {
         System.out.println("Hi");
     } else {
         System.out.println("BYE");
     }
                     

   • while (value < 4) {
         System.out.println(value++);
     }
                     

   • do {
         System.out.println(value++);
     } while (value < 4);
                     

   These examples are NOT OK:

   • if (value < 4)
         System.out.println("Hi");
                     

   • if (value < 4)
     {
         System.out.println("Hi");
     }
                     

   Switch statements are weird: You don't indent the cases. The correct style is:

   switch(value) {
   case 1:
       System.out.println("Something");
       break;
   default:
       throw new RuntimeException("value should be 1");
   }
               

3. Symbolic Constants
   

   Be sure to use symbolic constants instead of a literal, in most cases. Note that the correct style here is all capital letters with adjacent words separated by underscores. For example:

   Instead of this:

   totalArea = 6 * 17;
           

   Favor this:

   final static int FACES_ON_CUBE = 6;
   final static int AREA_PER_FACE = 17;
   ...
   
   totalArea = FACES_ON_CUBE * AREA_PER_FACE;
           

   Not EVERY literal needs to be a symbolic constant. For example, the literal 2.0, below is fine:

   triangleArea = (base * height) / 2.0;
           

   In cases of String literals, it is still a good idea to substitute symbolic constants, but we will not require it.

4. Length of Lines
   

   Do not write lines of code that are ridiculously long. Let's say for this semester that your line lengths should all be less than 120 characters.

5. Commenting
   

   Keep in mind that although everyone does commenting differently, the common goal is to make the code as readable as possible, and to make sure that other programmers who are relying on your API will understand everything they need to know.

   Although we would love it if you use Javadoc commenting, we will not require it.

   There should be comments in the following places:

   • At the top of every class/interface/enumeration. These comments should be general in nature, describing the purpose of the class and the "main idea" of it.
   • Above every method. These comments should be very, very detailed. Here you should describe the complete contract of the method including all pre-conditions and post-conditions. Be sure to mention the purpose of any parameters, the way the return value is calculated, any side effects that the method causes (including modification of the parameters, if they are mutable), exceptions that might be thrown and under what circumstances, etc. This is your opportunity to provide the "instruction manual" for another programmer who will be calling the method.
   • After most variable declarations. In addition to choosing good, descriptive names for your variables, it is usually a good idea to include short comment that clearly explains the role of the variable. This is not always necessary -- use your judgement.
   • Throughout the code. You should include comments here and there that would help the reader understand how the code behaves. Imagine your friend is looking at your code while you are standing nearby. What would you say to him/her to help them understand your code easily? Whatever you would say at that moment should be included as a comment within the code. These comments can appear beside conditionals, above loops, above blocks of code, anywhere you think they would help. Don't be stingy here -- most people err on the side of "not enough comments" rather than "too many comments".


6. Eliminating Redundancy
   

   Duplicative code is bad -- not so much because we care how long our code is, but mainly because duplication makes code maintenance very difficult and expensive! If you find your code has what is essentially the same code fragment in more than one place, try to eliminate the redundancy. Many times this can be accomplished by writing a separate method that contains the duplicated code fragment. Sometimes you can come up with better logic, or a clever use of one or more variables to aid in reducing redundancy.