Java Coding Standards  Ver. 1.

0 
Innova 
Solutions 

CODING STANDARDS 
FOR JAVA PROGRAMS 

DOC.ID  : JAVA­STD­DOC 

Version  : 1.0 

Effective From  : 19­09­2002 

Copy #  : 

INNOVA SOLUTIONS INDIA PVT LTD 
44, SAGAR SOCIETY, 
ROAD # 2, BANJARA HILLS 
HYDERABAD – 500 034.
 Java Coding Standards  Ver. 1.0 
Innova 
Solutions 

REVISION HISTORY 

Version 
Created/  Description  Affected 
Ref  Release  Reviewed 
Revised  of the  Sections in  Remarks 
(Releas  Date  by 
by  Revision  the Manual 
ed) 
The 
standards 
defined for 
19­09­  Surekha B  First time 
1.0  Kannan R  All sections  AQIVO is 
2002  S  release 
taken it 
organisatio 
n level

Innova Solutions India Pvt. Ltd.              For Internal Use Only                  Page I of III 
 Java Coding Standards  Ver. 1.0 
Innova 
Solutions 

TABLE OF CONTENTS 

INTRODUCTION....................................................................................................... 1 
FILE ORGANIZATION............................................................................................... 2 
JAVA SOURCE FILES .....................................................................................................2 
NAMING STANDARDS .............................................................................................. 3 
METHODS  .................................................................................................................3 
ACCESSOR METHODS ....................................................................................................3 
Getter methods ....................................................................................................3 
Setter Methods.....................................................................................................3 
ATTRIBUTES ...............................................................................................................3 
Variables .............................................................................................................4 
Streams ..............................................................................................................4 
Loop Counters......................................................................................................4 
Exception Objects .................................................................................................4 
Constants ............................................................................................................4 
Collections ...........................................................................................................5 
Method Parameters (Arguments) ............................................................................5 
CLASSES...................................................................................................................5 
INTERFACES ...............................................................................................................6 
PACKAGES .................................................................................................................6 
OBJECTS ...................................................................................................................6 
CODE FORMATTING ................................................................................................. 7 
STATEMENTS ..............................................................................................................7 
Simple Statements ...............................................................................................7 
Compound Statements ..........................................................................................7 
Return Statements ...............................................................................................7 
“if” Statements.....................................................................................................7 
“for” Statements ..................................................................................................8 
“while” Statements ...............................................................................................9 
“do­while” Statements ..........................................................................................9 
“switch” Statements .............................................................................................9 
“try­catch” Statements........................................................................................ 10 
DECLARATIONS ..................................................................................................... 11 
NUMBER PER LINE  ..................................................................................................... 11 
INITIALIZATION ......................................................................................................... 11 
DECLARATIONS ......................................................................................................... 11 
COMMENTS............................................................................................................ 12 
BLOCK COMMENTS ..................................................................................................... 12 
SINGLE­LINE COMMENTS ............................................................................................. 12 
GOTCHAS ............................................................................................................. 12 
GOTCHA Keywords ............................................................................................. 12 
GOTCHA Formatting............................................................................................ 13 
GUIDELINES FOR COMMENTS ......................................................................................... 13 
WHITE SPACE........................................................................................................ 14 
BLANK LINES  ........................................................................................................... 14

Innova Solutions India Pvt. Ltd.              For Internal Use Only                  Page II of III 
 Java Coding Standards  Ver. 1.0 
Innova 
Solutions 

BLANK SPACES ......................................................................................................... 14 
INDENTATION ....................................................................................................... 15 
LINE LENGTH......................................................................................................... 16 
WRAPPING LINES....................................................................................................... 16 
PROGRAMMING PRACTICES .................................................................................. 17 
PROVIDING ACCESS TO INSTANCE AND  CLASS VARIABLES ....................................................... 17 
REFERRING TO CLASS VARIABLES AND  METHODS ................................................................. 17 
CONSTANTS ............................................................................................................. 17 
VARIABLE A SSIGNMENTS .............................................................................................. 17 
MISCELLANEOUS P RACTICES .......................................................................................... 18 
Parentheses ....................................................................................................... 18 
Expressions before `?' in the Conditional Operator.................................................. 18 
Special Comments .............................................................................................. 18 
MISCELLANEOUS STANDARDS............................................................................... 19 
IMPORTING CLASSES .................................................................................................. 19 
PACKAGE AND  IMPORT STATEMENTS................................................................................. 19 
DOCUMENTATION OF CODE ................................................................................... 20 
COMPILATION UNIT HEADER .......................................................................................... 20 
CLASS AND  INTERFACE DOCUMENTATION ........................................................................... 20 
Documenting a Class........................................................................................... 20 
METHOD  DOCUMENTATION............................................................................................ 21 
The Method Header............................................................................................. 21 
Internal Documentation....................................................................................... 22 
COMPILATION UNIT DOCUMENTATION ............................................................................... 23 
APPENDIX A ­ JAVA SAMPLE PROGRAM LAYOUT ................................................... 24

Innova Solutions India Pvt. Ltd.              For Internal Use Only                  Page III of III 
 Java Coding Standards  Ver. 1.0 
Innova 
Solutions 

INTRODUCTION 
Code conventions are important to programmers for a number of reasons:

· 80% of the lifetime cost of a piece of software goes to maintenance.
·
· Hardly any software is maintained for its whole life by the original author.
·
· Code conventions improve the readability of the software, allowing engineers to 
understand new code more quickly and thoroughly. 

This  document  is  based  solely  on  the  Code conventions  for  Java  Language  from  Sun 
Microsystems.  Suitable  amendments  have  been  made  to  tailor  this  to  the 
requirements of the project.

Innova Solutions India Pvt. Ltd.              For Internal Use Only                  Page 1 of  25 
 Java Coding Standards  Ver. 1.0 
Innova 
Solutions 

FILE ORGANIZATION 

A  file  consists  of  sections  that  should  be  separated  by  blank  lines  and  an  optional 
comment  identifying  each  section.  Files  longer than  2000 lines  are  cumbersome  and 
should be avoided. 

Java Source Files 

Each Java source file contains a single public class or interface. When  private classes 
and  interfaces  are  associated  with  a  public  class,  you  can  put  them  in  the  same 
source file as the public class. The public class should be the first class or interface in 
the file. 

Java source files have the following ordering:

· Beginning comments
· Package and Import statements
· Class and interface declarations

Innova Solutions India Pvt. Ltd.              For Internal Use Only                  Page 2 of 25 
 Java Coding Standards  Ver. 1.0 
Innova 
Solutions 

NAMING STANDARDS 
Methods 

Methods should be named using a full English description, using mixed case with the 
first letter  of  any  non­initial  word  capitalized.  It is also  common practice for the first 
word of a method name to be a strong, active verb. 

Examples: 

openAccount() 
printMailingLabel() 
save() 
delete() 

Accessor Methods 

Getter methods 

Getters are methods that return the value of an attribute.  Prefix the word ‘get’ to the 
name of the attribute, unless it is a Boolean attribute and then prefix ‘is’ is added to 
the name of the attribute instead of ‘get.’ 

Examples: 

getFirstName() 
getAccountNumber() 
getLostEh() 
isPersistent() 
isAtEnd() 

Setter Methods 

Setters are methods that modify the values of an attribute. Prefix the word ‘set’ to the 
name of the attribute, regardless of the attribute type. 

Examples: 

setFirstName(String aName) 
setAccountNumber(int anAccountNumber) 
setReasonableGoals(Vector newGoals) 
setPersistent(boolean isPersistent) 
setAtEnd(boolean isAtEnd) 

Attributes 

Fields/Properties

Innova Solutions India Pvt. Ltd.              For Internal Use Only                  Page 3 of 25 
 Java Coding Standards  Ver. 1.0 
Innova 
Solutions 

Variables 

Use a full English descriptor to name attributes to make it obvious what the attribute 
represents.  Attributes that are collections, such as arrays or vectors, should be given 
names  that  are  plural  to  indicate  that  they  represent  multiple  values.  Use  the 
following prefixes 

b for Boolean 
str stands for string 
i for Integer 
db for double 
f for float 

Examples: 

strfirstName 
strzipCode 
dbunitPrice 
dbdiscountRate 
iorderItems 

Streams 

When  there  is  a  single  input  and/or  output  stream  being  opened,  used,  and  then 
closed  within  a  method  the  common  convention  is  to  use  the  prefixes  “ip”  and 
“op”  respectively  for  the  names  of  these  streams.    For  a  stream  used  for  both 
input and output, the implication is to use the prefix  “io”. 

Examples: 

ipFileInputStream 
opFileOutputStream 
ioFileIOStream 

Loop Counters 

The  use  of i, j,  or k is  acceptable  for  loop  counters.    Use  these  names  for  loop 
counters consistently. 

Exception Objects 

Because exception handling is very common in Java coding use the suffix “exception” 
for an exception. 

Constants 

Constants,  values  that  do  not  change,  are  typically  implemented  as  static  final 
attributes of classes. 
Use full English words, all in uppercase, with underscores between the words.

Innova Solutions India Pvt. Ltd.              For Internal Use Only                  Page 4 of 25 
 Java Coding Standards  Ver. 1.0 
Innova 
Solutions 

Examples: 

MINIMUM_BALANCE 
MAX_VALUE 
DEFAULT_START_DATE 

Collections 

A  collection,  such  as  an  array  or  a  vector,  should  be  given  a  pluralized  name 
representing  the  types  of  objects  stored  by  the  array.  The  name  should  be  a  full 
English descriptor with the first letter of all non­initial words capitalized. These are to 
carry the following prefixes – 

ar  array 
vr  vector 
ht  hash table 
ll  Linked List 

Examples: 

arCustomers 
vrOrderItems 
htAliases 
llLogQueue 

Method Parameters (Arguments) 

Parameters  should  be  named  following  the  exact  same  conventions  as  for  local 
variables. 

Examples: 

// str for String 
strCustomer 
//db for double 
dbInventoryItem 
// b for Boolean 
bPhotonTorpedo 

Classes 

Use  a full English descriptor starting with the first letter capitalized using mixed case 
for the rest of the name. Class names are prefixed with the letter ‘C’ 

Examples: 

CCustomer 
CEmployee 
COrder 
COrderItem 
CFileStream 
CString

Innova Solutions India Pvt. Ltd.              For Internal Use Only                  Page 5 of 25 
 Java Coding Standards  Ver. 1.0 
Innova 
Solutions 

Interfaces 

Interface  names  should  be  follow  class­naming  conventions,  except  that  these  are 
prefixed by the letter ‘I’ to indicate an interface. 

Examples: 

interface ISessionManager 

Packages 

Packages are named as follows – 

com.<project name>.<layer>.<module> 

Example: 

package com.aqivo.bll.email 
package com.aqivo.pl.contacts 
package com.aqivo.sb.exchange 

Objects 

All the object names should start with “obj” and followed by the name of the object.

Innova Solutions India Pvt. Ltd.              For Internal Use Only                  Page 6 of 25 
 Java Coding Standards  Ver. 1.0 
Innova 
Solutions 

CODE FORMATTING 
Statements 

Simple Statements 

Each line should contain at most one statement. Example: 

counter++;  // Correct 
index­­;  // Correct 
counter++; index­­;  // Not allowed 

Compound Statements 

Compound  statements  are  statements  that  contain  lists  of  statements  enclosed  in 
braces as 

{ 
Statements 
}

· The enclosed statements should be indented one more level than the compound 
statement.
·
· The opening brace should be at the beginning of the next line.
·
· The closing brace should begin a line and be indented to the beginning of the 
compound statement.
·
· Braces are used around all statements; even single statements, when they are 
part of a control structure, such as an  if­else  or  for  statement. This makes it 
easier to add statements without accidentally introducing bugs due to forgetting 
to add braces. 

Return Statements 

A  return  statement  with  a  value  should  not  use  parentheses  unless  they  make  the 
return  value  more obvious in  some  way.  Do not  use any expression as part of  the 
return statement. 

Example: 

return; 
return myDisk.size(); 

“if” Statements 

The  if­else  class of statements should have the following format.

Innova Solutions India Pvt. Ltd.              For Internal Use Only                  Page 7 of  25 
 Java Coding Standards  Ver. 1.0 
Innova 
Solutions 

if (condition) 
{ 
statements; 
} 

if (condition) 
{ 
statements; 
} 
else 
{ 
statements; 
} 

if (condition) 
{ 
statements; 
} 
else if (condition) 
{ 
statements; 
} 
else 
{ 
statements; 
} 

Note:  if  statements always use braces {}. Avoid the following error­prone form: 

if (condition)  // NOT ALLOWED 
statement; 

“for” Statements 

A  for  statement should have the following form: 

for (initialization; condition; update) 
{ 
statements; 
} 

Avoid  empty  for  statements  (one  in  which  all  the  work  is  done  in  the  initialization, 
condition, and update clauses).

Innova Solutions India Pvt. Ltd.              For Internal Use Only                  Page 8 of 25 
 Java Coding Standards  Ver. 1.0 
Innova 
Solutions 

“while” Statements 

A  while  statement should have the following format. 

while (condition) 
{ 
statements; 
} 

Avoid empty “while”  statements. 

“do­while” Statements 

A  do­while  statement should have the following form: 

do 
{ 
statements; 
} while (condition); 

“switch” Statements 

A  switch  statement should have the following format. 

switch (condition) 
{ 
case ABC: 
statements; 
/* falls through */ 

case DEF: 
statements; 
break; 

case XYZ: 
statements; 
break; 

default: 
statements; 
break; 
} 

Every  time  a  case  falls  through  (doesn't  include  a  break  statement)  add  a  comment 
where  the  break  statement  would  normally  be.  This  is  shown  in  the  preceding  code

Innova Solutions India Pvt. Ltd.              For Internal Use Only                  Page 9 of 25 
 Java Coding Standards  Ver. 1.0 
Innova 
Solutions 

example  with  the  /*  falls  through  */  comment.  Every  switch  statement  should 
include a default case. 

“try­catch” Statements 

A try­catch statement should have the following format. 

try 
{ 
statements; 
} 
catch (ExceptionClass e) 
{ 
statements; 
} 
finally 
{ 
statements; 
} 

A  try­catch  statement  may  also  be  followed  by  finally,  which  executes  regardless  of 
whether or not the  try block has completed successfully.

Innova Solutions India Pvt. Ltd.              For Internal Use Only                  Page 10 of 25 
 Java Coding Standards  Ver. 1.0 
Innova 
Solutions 

DECLARATIONS 
Number Per Line 

One  declaration  per  line  is  recommended  since  it  encourages  commenting.  The 
declaration should be followed by a very short comment line as described below. 

int level; // indentation level 
int size;  // size of table 

Initialization 

Try to initialize local variables where they're declared. The only reason not to initialize 
a  variable  where  it's  declared  is  if  the  initial  value  depends  on  some  computation 
occurring first. All the variables should be initialized with a value as follows.

· References should be initialized to  NULL
· Numeric should be initialized to 0 [zero].
· Strings should be initialized to NULL.
· Boolean should be initialized to ‘FALSE’ 

Declarations 

Put  declarations only  at  the beginning of blocks.  Don't  wait to  declare  variables  until 

their first use. 

void myMethod() 
{ 
int int1 = 0;         // beginning of method block 

if (condition) 
{ 
int int2 = 0;     // beginning of "if" block 
... 
} 
} 

The one exception to the rule is indexes of  for  loops, which in Java can be declared in 

the  for  statement: 

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

Innova Solutions India Pvt. Ltd.              For Internal Use Only                  Page 11 of 25 
 Java Coding Standards  Ver. 1.0 
Innova 
Solutions 

COMMENTS 
Use  doc  conventions  for  class  and  method  headers  only.  Documentation  comments 
(known as "doc comments") are delimited by /**...*/. 

Comments  should  be  used  to  give  overviews  of  code  and  provide  additional 
information  that  is  not  readily  available  in  the  code  itself.  Comments  should  contain 
only information that is relevant to reading and understanding the program. 

Block Comments 

A  block  comment  should be  preceded  by a  blank line  to  set  it  apart  from  the  rest  of 
the code.  These comments should follow the structure below. 

/* 
* Here is a block comment. 
*/ 

Single­Line Comments 

Short  comments  can  appear  on  a  single  line  indented  to  the  level  of  the  code  that 
follows.  If  a  comment  can't  be  written  in  a  single  line,  it  should  follow  the  block 
comment format.  A blank line should precede a single­line comment. 

if (condition) 
{ 

// Handle the condition. 
... 
} 

GOTCHAS 

Explicitly  comment  variables  changed  out  of  the  normal  control  flow  or  other  code 
likely to break during maintenance. Embedded keywords are used to point out issues 
and potential problems. 

GOTCHA Keywords

· :TODO: topic ­ means there's more to do here, don't forget.
· :BUG: [bugid] topic ­ means there's a Known bug here, explain it and optionally 
give a bug ID.
· :KLUDGE ­ When you've done something ugly say so and explain how you would 
do it differently next time if you had more time.
· :TRICKY ­ Tells somebody that the following code is very tricky so don't go 
changing it without thinking.
· :WARNING ­ Beware of something.
· :COMPILER­ Sometimes you need to work around a compiler problem. Document 
it. The problem may go away eventually.

Innova Solutions India Pvt. Ltd.              For Internal Use Only                  Page 12 of 25 
 Java Coding Standards  Ver. 1.0 
Innova 
Solutions 

GOTCHA Formatting

· Make the gotcha keyword the first symbol in the comment.
· Comments may consist of multiple lines, but the first line should be a self­ 
containing, meaningful summary.
· The writer's name and the date of the remark should be part of the comment. This 
information is in the source repository, but it can take a quite a while to find out 
when and by whom it was added. Often gotchas stick around longer than they 
should. Embedding date information allows other programmer to make this 
decision. Embedding who information lets us know who to ask. 

Guidelines for Comments

· Comment the Data declarations
· Assumptions made about input and output variables (range of allowable values, 
accuracy).
· Assumptions made in other parts of the program (for example, user interface).
· Changes made to fix bugs in earlier versions.
· Describe code that violates programming conventions (along with reasons for the 
violation).
· Detail the public data being used / modified in a method.

Innova Solutions India Pvt. Ltd.              For Internal Use Only                  Page 13 of 25 
 Java Coding Standards  Ver. 1.0 
Innova 
Solutions 

WHITE SPACE 

Blank Lines 

Blank  lines  improve  readability  by  setting  off  sections  of  code  that  are  logically 
related.

· Two blank lines should always be used in the following circumstances –

· Between sections of a source file
· Between class and interface definitions

· One blank line should always be used in the following circumstances –

· Between methods
· Between the local variables in a method and its first statement
· Between logical sections inside a method to improve readability 

Blank Spaces 

Blank spaces should be used following the guidelines below.

· A keyword followed by a parenthesis should be separated by a space. 

while (true) 
{ 
... 
} 

Note:    that  a  blank  space  should  not  be  used  between  a  method  name  and  its 
opening  parenthesis.  This  helps  to  distinguish  keywords  from  method  calls.  Never 
leave  any  white  spaces  at  the  end  of  a  statement  /  line.  Type  casts  should  not  be 
followed by a blank space. 

A  blank  space  should  appear  after  commas  in  argument  lists.  A  blank  space  also 
appears after a semi­colon in expressions. All binary and ternary operators should be 
separated from their operands  by  spaces.  Blank  spaces  should  never  separate  unary 
operators from their operands. 

Example: 

a += c + d; 
a  = (a + b) / (c * d); 

while (d++ = s++) 
{ 
n++; 
}

Innova Solutions India Pvt. Ltd.              For Internal Use Only                  Page 14 of  25 
 Java Coding Standards  Ver. 1.0 
Innova 
Solutions 

printSize("size is " + foo + "\n"); 

for (expr1; expr2; expr3) 
myMethod((byte) aNum, (Object) x); 
myMyMethod((int) (cp + 5), ((int) (i + 3)) + 1); 

INDENTATION 

The  readability  of  a  program  improves  extensively  with consistent  indentation.  Good 

programming  style  dictates  that  the  loop  structure  is  indented  i.e.  shifted  right 
relative to the loop statement. Moreover, indentation acts as an important visual aid 
to the programmer, helping to match the open and close brackets in loop structures. 
Try to use the tools provided by the IDE used to format the code.

Innova Solutions India Pvt. Ltd.              For Internal Use Only                  Page 15 of 25 
 Java Coding Standards  Ver. 1.0 
Innova 
Solutions 

LINE LENGTH 
Avoid  lines  longer  than  80  characters,  since  they're  not  handled  well  by  many 
terminals  and  tools.    Usage  of  Word­wrap is  always  suggested.  Examples  for  use  in 
documentation  should  have  a  shorter  line  length­generally  no  more  than  70 
characters. 

Wrapping Lines 

When  an  expression  will not  fit on  a  single  line,  break  it  according  to  these  general 
principles.

· Break after a comma.

· Break before an operator.

· Align the new line with the beginning of the expression at the same level on the 
previous line.

· If the above rules lead to confusing code or to code that's squished up against the 
right margin, rewrite the code to break up the statement – it is too complex.

· The open brace of the method should start in the first column.

· The inner loop structure should start from the fifth position of the outer loop 
structure.

· If there are multiple assignments in any block, then all the assignment operators 
should be vertically aligned.

· All closing braces should be vertically aligned with the corresponding open 
braces.

Innova Solutions India Pvt. Ltd.              For Internal Use Only                  Page 16 of  25 
 Java Coding Standards  Ver. 1.0 
Innova 
Solutions 

PROGRAMMING PRACTICES 

Providing Access to Instance and Class Variables 

Don't make any instance or class variable public without good reason. Often, instance 
variables don't need to be explicitly set or gotten­often that happens as a side effect 
of method calls. 

Referring to Class Variables and Methods 

Avoid using an object to access a class (static) variable or method. Use a class name 
instead. For example: 

classMethod();             //OK 
AClass.classMethod();      //OK 
anObject.classMethod();    //AVOID! 

Constants 

Numerical  constants  (literals)  should  not  be  coded  directly,  except  for  ­1,  0,  and  1, 
which can appear in a for loop as counter values. 

Variable Assignments 

Avoid assigning several variables to the same value in a single statement. It is hard to 
read. Example: 

fooBar.fChar = barFoo.lchar = 'c'; // AVOID! 

Do not  use  the  assignment  operator  in a  place  where it  can  be  easily confused  with 
the equality operator. Example: 

if (c++ = d++) {        // AVOID! (Java disallows) 
... 
} 

should be written as 

if ((c++ = d++) != 0) { 
... 
} 

embedded  assignments  in  an  attempt  to  improve  run­time  performance. 

Do  not  use 
This is the job of the compiler. Example: 

d = (a = b + c) + r;        // AVOID! 

should be written as 

a = b + c; 
d = a + r;

Innova Solutions India Pvt. Ltd.              For Internal Use Only                  Page 17 of 25 
 Java Coding Standards  Ver. 1.0 
Innova 
Solutions 

Miscellaneous Practices 

Parentheses 

It is generally a good idea to use parentheses liberally in expressions involving mixed 
operators  to  avoid  operator  precedence  problems.  Even  if  the  operator  precedence 
seems  clear  to  you,  it  might  not  be  to  others­you  shouldn't  assume  that  other 
programmers know precedence as well as you do. 

if (a == b && c == d)     // AVOID! 
if ((a == b) && (c == d)) // RIGHT 

Expressions before `?' in the Conditional Operator 

If  an  expression  containing  a binary operator  appears  before the ?  in  the  ternary  ?: 
operator, it should be parenthesized. Example: 

(x >= 0) ? x : ­x; 

Special Comments 

Use XXX  in  a  comment  to  flag something  that  is  bogus  but  works. Use  FIXME  to flag 
something that is bogus and broken

Innova Solutions India Pvt. Ltd.              For Internal Use Only                  Page 18 of 25 
 Java Coding Standards  Ver. 1.0 
Innova 
Solutions 

MISCELLANEOUS STANDARDS 
Importing Classes 

Fully qualify the name of the classes that your code uses. 

Example: 

import java.awt.Color; 
import java.awt.Button; 
import java.awt.Container; 

It  is  advisable  to  import  the  specific  class  that  is  used,  viz.,  java.util.Vector  instead  of  java.util.*  . 
Avoid usage of * while importing. 

Package and Import Statements 

The  first  non­comment  line  of  most  Java  source  files  is  a  package  statement.  After 
that,  import  statements can follow. 

package java.awt; 
import java.awt.peer.CanvasPeer;

Innova Solutions India Pvt. Ltd.              For Internal Use Only                  Page 19 of 25 
 Java Coding Standards  Ver. 1.0 
Innova 
Solutions 

DOCUMENTATION OF CODE 

Compilation Unit Header 
// 15­Nov­98; ravinv; 
// name change of  myResultSet/myResultSetBase to 
//  ResultSet/ResultSetBase incorporated 
// Source file: package/package/QueryBroker.java 

package com.innova.sbu1cbu2.dbtools; 

import java.util.Vector; 
import java.util.Properties; 

Class and Interface Documentation 
/** 
*  This class provides the Transaction Execution Service. 
*  The clients submit their transaction and QueryBroker executes the 
*  queries present in the transaction set. The results and status of 
*  execution are made available to the client. 
*  This class keeps a set of connection pools associated with 
*  the set of servers[abstraction of dB server]. 
*  When a transaction is submitted, the QueryBroker finds an 
*  appropriate Connection and executes the transaction and returns the 
*  result in the passed transaction object. 
*  The number of Connections for the Connectionpool is read as property. 
*  @author Ramkumar Balasubramaniam\Innova Solutions India 
*  @version 0.9 10­Nov­1998 
*
*/ 

Documenting a Class 

The following information should appear in the documentation comments ­ 

The development/maintenance history of the class 

It  is  common  practice  to  include  a  history  table  listing  dates,  authors,  and 
summaries  of  changes  made  to  a  class.  The  purpose  of  this  is  to  provide 
maintenance  programmers  insight  into  the  modifications  made  to  a  class  in  the 
past,  as  well  as  to  document  what  has been  done  what  to  a class  and by  whom. 
This record is to be maintained at the end of the file that contains class. 

Name of the compilation unit 

This  is  necessary  to  identify  the  compilation  unit  (source  code/files)  from 
printouts. 

The purpose of the class

Innova Solutions India Pvt. Ltd.              For Internal Use Only                  Page 20 of 25 
 Java Coding Standards  Ver. 1.0 
Innova 
Solutions 

Developers  need  to  know  the  general  purpose  of  a  class  so  they  can  determine 
whether  it  meets  their  needs.  Make  it  a  habit  to  document  any  good  things  to 
know about a class, for example is it part of a pattern or are there any interesting 
limitations to using it. 

The concurrency strategy 

Any  class  that  implements  the  interface  “Runnable” should  have  its  concurrency 
strategy  fully  described.  Common  concurrency  strategies  include  the  following: 
Synchronized  objects,  balking  objects,  guarded  objects,  versioned  objects, 
concurrency policy controllers, and acceptors. 

Method Documentation 
/**
*This method returns the current size of the specified connection 
* pool. 
* @param  Parm1  xxxxxx 
* @param  Parm2  yyyyyy 
* @param  Parm3  zzzzzz 
* @return  xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx 
* @exception1  xxxx 
* @exception2  yyyy 
* @exception3  zzzz 
* @author Kannan/Innova Solutions India 
* @version 1.0 10­Jul­2001 
*/ 

Documenting  a  method  is  often  the  deciding  factor  as  to  whether  or  not  it  is 
understandable, and therefore maintainable and extensible. 

The Method Header 

Every Java method should include some sort of header, called method documentation, 
at the top of the source  code that documents  all of the information that is critical to 
understanding it. This information includes, but is not limited to the following. 

What the method can perform? 

By  documenting  what  a  method  can  offer other  classes  if  they  have  to  reuse  the 
code.  Documenting  why it  does  something  and  makes  it  easier  for  others  to  put 
the code into context. 

What parameters must be passed to a method? 

Indicate what parameters, if any, must be passed to a  method and how they will 
be  used.  This  information  is  needed  so  that  other  programmers  know  what 
information to pass to a method. Use the javadoc @param tag for this purpose. 

What does the method return?

Innova Solutions India Pvt. Ltd.              For Internal Use Only                  Page 21 of 25 
 Java Coding Standards  Ver. 1.0 
Innova 
Solutions 

Document what, if anything, a method returns so that other programmers can use 
the  return  value/object  appropriately.  Use  the javadoc @return tag  for  this 
purpose. 

Exceptions thrown by the method 

Document  any  and  all  exceptions  that  a  method  throws  so  that  other 
programmers know what their code will need to catch. Use the javadoc @exception
tag for this purpose. 

A history of any code changes 

Whenever a change is made to a method, document when the change was made, 
who made it and why it was made. This history information is critical for the future 
maintenance  programmers  who  are  responsible  for  modifying  and  enhancing  the 
code. 

Internal Documentation 

In addition to the method documentation, you also need to include comments within 
methods  to  clarify  the  logic.  The  following  are  the  general  guidelines  for  internal 
method documentation. 

Control structures 

Describe  what  each  control  structure,  such  as  comparison  statements  and  loops. 
One shouldn’t have to read all the code in a control structure to determine what it 
does,  instead  one  should  just  have  to  look  at  a  one  or  two  line  comment 
immediately preceding it. 

Business Rules implemented by the code 

You  can  always  look  at  a  piece of  code  and  figure  out what  it  does,  but  for  code 
that isn’t obvious you can rarely determine why it is done that way. 

For  example,  you  can  look  at  a  line  of  code  and  easily  determine  that  a  5% 
discount is being applied to the total of an order. That is easy. What isn’t easy is 
figuring out WHY that discount is being applied. 

Obviously  there is  some  sort of  business  rule  that  says  to  apply  the  discount,  so 
that  business  rule  should  at  least  be  referred  to  in  your  code  so  that  other 
developers can understand why your code does what it does. 

Local variables

Each local variable defined in a method should be declared on its own line of code 
and should usually have an inline comment describing its use.

Innova Solutions India Pvt. Ltd.              For Internal Use Only                  Page 22 of 25 
 Java Coding Standards  Ver. 1.0 
Innova 
Solutions 

Difficult or complex code 

Document  thoroughly  any  complex  code  in  a  method.  General  rule  of  thumb  is 
that if the code isn’t obvious, then you need to document it. 

The processing order 

If there are statements in your code that must be executed in a defined order then 
you should ensure that this fact gets documented. 

Compilation Unit Documentation 

It  sometimes  makes  sense  to  define  several  classes  (or  interfaces)  in  the  same  file. 
We  have  separate  documentation  conventions  that  apply  to  a  source  code  file,  and 
not  specifically  to  a  class,  when  the  source  code  file  includes  multiple  classes.  This 
documentation must appear at the top of the source code file. 

For files with several classes, list each class 

If  a  file  contains  more  than  one  class,  provide  a  list  of  the  classes  and  a  brief 
description for each. A separate block is to be used for each class in the file, at the 
end of the file. 

The file name and/or identifying information 

The advantage is that if the code is printed you know what the source file for the 
code is.

Innova Solutions India Pvt. Ltd.              For Internal Use Only                  Page 23 of 25 
 Java Coding Standards  Ver. 1.0 
Innova 
Solutions 

APPENDIX A ­ JAVA SAMPLE PROGRAM LAYOUT 
/* 
* @(#)Blah.java  1.00  2001/07/24 
* 
* Copyright (c) 2001­2002 Mobile Airwaves Inc. 
* 758 Clementina San Francisco, California 94103, U.S.A. 
* All rights reserved. 
* 
* This software is the confidential and proprietary information of 
* Mobile Airwaves, Inc. ("Confidential Information").  You shall not 
* disclose such Confidential Information and shall use it only in 
* accordance with the terms of the license agreement you entered into 
* with Mobile Airwaves, Inc. 
*/ 

package com.aqivo.pl.email; 

import java.blah.blahdy.blahblah; 

/** 
* Class description goes here. 
* 
* @version  1.82 18 Mar 1999 
* @author  Firstname Lastname 
*/ 
public class Blah extends SomeClass { 
/* A class implementation comment can go here. */ 

/** classVar1 documentation comment */ 
public static int classVar1; 

/** 
* classVar2 documentation comment that happens to be 
* more than one line long 
*/ 
private static Object classVar2; 

/** instanceVar1 documentation comment */ 
public Object instanceVar1; 

/** instanceVar2 documentation comment */ 
protected int instanceVar2; 

/** instanceVar3 documentation comment */ 
private Object[] instanceVar3; 

/** 
* ...constructor Blah documentation comment... 
*/ 
public Blah() { 
// ...implementation goes here... 
}

Innova Solutions India Pvt. Ltd.              For Internal Use Only                  Page 24 of  25 
 Java Coding Standards  Ver. 1.0 
Innova 
Solutions 

/** 
* ...method doSomething documentation comment... 
*/ 
public void doSomething() { 
// ...implementation goes here... 
} 

/** 
* ...method doSomethingElse documentation comment... 
* @param someParam description 
*/ 
public void doSomethingElse(Object someParam) { 
// ...implementation goes here... 
} 
} 

/* 
* Modification History 
* Mod#  Modified by  Date  Desciription 
*  1  Sofware Engineer  2001­07­25  Blah blah blah blah blah 
*  blah blah blah blah 
* 
*/

Innova Solutions India Pvt. Ltd.              For Internal Use Only                  Page 25 of 25