Java coding standards and Javadoc style comments

Formatting Conventions

Indent nested code
Nested code improves readability. Every time that you open a bracket you should indent the code written after it. The indentation should continue until the bracket is closed. The indentation should not be that of a tab. Tab indentation is too much and will make code harder to read instead of easier. Three spaces is the best indentation.
(That is what you should do for ICS111)

About brackets...
You should always open a bracket at the end of a statement. You should always close the bracket at the beginning of a line.

Class

public class MyClass{
   ...
}

Method definitions

void method(int j){
   ...
}

Loops

for(int i = 0; i<=j; i++){
   ...
}

If/else statements

if(j<0){
   ...
}
else if(j>0){
   ...
}
else{
   ...
}

Try/Catch/Finally

try{
   ...
}
catch(Exception e){
   ...
}
finally{
   ...
}

Switch

switch(value){
   case 0:
	...
	break;
   default:
	...
	break;
}

White Space
Code needs some strategically located white space to improve readability.  Use blank lines to separate each logical section of the program.

Naming Conventions

Use meaningful names for your classes and your methods follow the specific conventions mentioned here.

  • Do not use names that are too long
    int iSchoolIdentificationNumber
    
  • Capitalize only the first letter in acronyms.
    int iPdaNumber; //instead of PDA
    
  • Capitalize the first letter of each word that appears in a class or interface name.
    public class MyClass
    
  • Use nouns when naming classes
  • Use nouns or adjectives when naming interfaces.
  • For method names use lowercase for the first word and capitalize only the first letter of each of the remaining words. Use verbs as names for methods.
    public void loveFinder(String s) 
    
  • For variable names use lowercase for the first word and capitalize only the first letter of each of the remaining words. Use nouns as names for variables.
    int iBookEntries 
    
  • To name constants use uppercase for each word and separate each pair of words with an underscore. This is only applicable in constant naming.
    final double PI = 3.1416;
    final int MAX_COUNT = 27;
    
  • Use descriptive names for all variables, function names, constants, and other identifiers. 
  • Use single letter identifiers only for the counter in loops.
  • Variable names start with lower case.
  • Multi-word identifiers are internally capitalized.
  • Do not use hyphens or underscores to separate multi-word identifiers.

JAVADOC style comments

Every documentation comment begins with:
"/**"
and ends with
"*/"

A one-line comment begins with "//"

  • Use one-line comments to explain implementation details such as the purpose of specific variables and expressions.
  • int iCountPer=0; //counts persons
    
  • Explain local variable declarations with and end-line comment.

Every class and method should be preceded with a descriptive comment using the "JavaDoc" notational convention. 

In the class, the comment should name the class, describe its purpose, and name the author.

 
/**
 * Hello1 --- program to print "Hello World".
 * @author    Blanca Polo
 */
public class Hello1 {
 :
}

In the method, the comment should describe its purpose, comment all arguments, the return value, and any exceptions using JavaDoc keywords.

 
 /**
   * Prints out "Hello World" 
   * and the command line arguments.
   * @param arg A string array containing 
   * the command line arguments.
   * @exception Any exception
   * @return No return value.
   */ 
  public static void main (String[] arg){
   :
  }

Programming Conventions

  • Make all fields private, doing so ensures consistency of the member data because only the owning member can make changes to it.
  • Clarify the order of operations with parenthesis.
  • Always code a break statement in the last case of a switch statement
  • Use the keyword this to distinguish field variables from local variables.
  • When a constructor or set method assigns a parameter to a field, give that parameter the same name as the field.

"No standard is perfect and no standard is universally applicable. Sometimes you will  find yourself in a situation where you need to deviate from the established standard. Before you decide to ignore a rule, you should first make sure you understand why the rule exists and what the consequences are if it is not applied. If you decide you must violate a rule, then document why you have done so."*