<Dokument für das Datenbankpraktikum>

Java Style Guidelines

Lars Knipping, Gerald Weber

Java Standard Guidelines

• Use Java doc comments (/** ... */) for all members, including private members. Use the @author and @version tag. Use for technical comments a tag named @technical. Use standard Java doc comment layout.

• Class and Interface names start with capitals. In multiple word names new words start with capitals:
  public class MyClass {
  }
  Package names are completely lowercase:
  import com.sun.java.swing;
  Variable and method names start with small letters (multiple words see classes)
  void updateStatus();
  Constant names are completely uppercase, multiple words are separated by underlines:
  final static int MAX_SIZE = 0;
• Class names are nouns.
  Exception class names end on ...Exception.
  Interface names are adjectives, preferrably ending on ...able or ...ible.
  Method names are verbs, especially getSomething, setSomething, isSomething. Do not use the rule "every noun can be verbed", use existing verbs instead.
• The parameter of the catch-block is called e.

try{ //...
}catch(IOException e){ //...
}

• Braces are set in the following way:

while(object.isBusy()){
  sleep(1000);
}

Further Naming Guidlines for this project

• Use C-style comments (/* ... */) never for documentation, only for excluding code.
• Use a so called slashbar (/////////) before methods (before their doc comment) to separate them optically.
• No new exception extends RuntimeException.
• Class names are singular.
• Class modifiers are ordered: public final abstract
  Abstract classes always get the abstract modifier in the class declaration.
• Class members are ordered:
  Constants, variables, methods; within each group:
  Private, protected, public; within each group:
  static, then the rest.
• MOST IMPORTANT: The a-Rule
  Exactly those variables which are initialized immediately and always contain an object have names starting with a or an resp. :

Frame aFrame = new Frame();
Object anObject;
try{
anObject = MyObjectService.loadObject();
}catch(MyLoaderException e){
   handle(e);
}

Nouns in get and set method names are treated accordingly:
myString = getParameter(MY_KEY);
aYourString = getAName(); // never returns null

Variables and methods with a or an are preferred. The a-rule applies also to method parameters, indicating whether the method makes a check for null or not.

• ESPECIALLY IMPORTANT: The underline-Rule
  Local variable names start with an underline: _local;
  Member variables end with an underline: private Frame aFrame_;
  Method parameters have no underline.
• The first choice for the name of a variable is the type name:
  Frame aFrame;
  Panel panel;
  Instances of container classes are named by the container class name followed by Of, followed by the type of objects stored. The a-rule is applied for each part, no plurals please:
  AListOfAnEvent, AVectorOfString.

• Blocks are indented by two blanks (dutch mountains rule).
• Each appropriate control structure is followed by a block, except else followed by if (so called elsif). No further blocks are used. An elsif example:

if(isGood){
  buyProduct();
}else if(isBad){
  writeLetter();
}else{
  moanAbout();
}

• In a switch statement all cases are terminated by a break; command or a //fallthrough comment:

switch(quality){
case 1:
  buyProduct();
  break;
case 3: case 4:
  writeLetter();
  //fallthrough
case 2:
  warnOther();
  break;
default:
  moanAbout();
  break; 
}

• for is used only for counting loops or traversing lists, and so called "forever"-loops :
  for(;;){
  }
• Counting variables are preferrably called i,j,k,l,m,n
  Start counting from zero as often as possible.
  Use ++i rather than i++
• Assignment operators are surrounded by blanks, except in the for statement. Use blanks in expressions sparsely. There are no blanks between method names and parameter parentheses. A comma is followed by a blank:

for(i=0; i<MAX_INDEX; ++i) {
  processIndex(i);
}
aMaxResult = aResponder.getAResult(aResultSet, aQuery);

• String Literals are never directly used as method parameters.
• Define as class constants: tokens from official standards ("POST", "throws"), property keys, property file names, internal error messages.
• Other strings are defined in property files (using the usual java style). The property file names should have the form xxx-language.prp (because .property was a really bad idea).
• Properties are always accessed by aProperties.getProperty(KEY, KEY), so that at least the key is printed.
• compile always with -g or without optimization.
• Long parameter lists or expressions are wrapped as follows (rationale: all subexpressions on one level are put into separate lines before any of them are broken):

method(parameter1, param2part1+param2part2, parameter3);
myVariable = summand1+summand2part1*summand2part2+summand3;


method(
  aParameter1, param2part1+param2part2, aParameter3);


method(
  aParameter1, 
  param2part1+param2part2, 
  aParameter3);

myVariable = 
    summand1
  + summand2teil*summand2teil2)
  + summand3;

method(
  aParameter1, 
  param2part1+param2part2, 
  parameter3);

myVariable = 
    summand1
  + summand2teil*summand2teil2)
  + summand3;
method(
  aParameter1, 
  param2part1
   +param2part2, 
  aParameter3);

myVariable = 
    summand1
  + summand2teil
    *summand2teil2
  + summand3;

But never:

method( 
  aParameter1, param2part1+            // never
  param2part2, aParameter3);           // never

myVariable = summand1+summand2teil1    // never
            *summand2teil2+summand3;   // never