Java Coding Standards

Computer Science Department

College of Charleston

 

The goal of good programming style is to make the program human readable, not only for the programmer developing the program, but for the programmer who will maintain the code later, and for a user who wants to know if the program will perform the tasks which he/she needs. 

 

1.  Comments:

A.  At the beginning of the program there should be a header block of comments.  Frame the header by using a row of =, *, or something similar proceeding and following the header. The header should contain the following:

 

Author:

<Programmer’s name>

Date:

<Give date program is due.>

Class:

<Provide the course and section numbers>

Assignment:

<Provide the number of the assignment>

Task:

<Provide a simple, yet complete description of the task being performed by this program.>

Input:

<Tell what input is needed.  Include any restrictions on the input.  State the source of the input: keyboard or file.  If input is from a file, give the file name, if required, and the format of the file.>

Output:

<Describe the results produced by the program.  You do not need to mention prompts for input.>

 

Certification of Authenticity:   <include one of the following>
                           I certify that this lab is entirely my own work.  
                    I certify that this lab is my own work, but I received some assistance from:        
                                <Name(s)>

(See the course collaboration policy to determine what types of assistance are allowed.)

 

B.  Variable and Object declarations should have a comment stating their purpose or use.

 

C.  At the beginning of each method, there should be a block of comments giving:

 

Purpose:

<Describe what the method does.>

Preconditions:

<Values expected in parameters when the method is entered.>

Postconditions:

<Values in parameters and return value when the method is exited.>

 

D.  Comments in the body of the program: These should not state the obvious.  Explain why something is being done as opposed to how something is being done.  For example:

         counter = 0;  // set counter to 0  (not good)
         counter = 0;  // nothing encountered yet  (better)

Use block comments to describe the purpose of a section of code, or to explain the purpose of any code that may raise a question in the reader’s mind about its function.  There may also be comments at the end of a line that apply only to that line, and do not extend beyond the readable portion of the code (approx. 80 columns).

 

Write all documentation as if the reader is computer literate and basically familiar with the Java language.  In the academic environment, document any code that does not function properly explaining the errors it causes and any possible explanation you have for these errors.  (Note: In the professional environment, never release code with known errors.)

 

2.  Naming:

Make identifier names meaningful and easy to read.  They should be reasonably short.  Good choice of identifiers helps the code become self-documenting.

 

Constants:  Use UPPERCASE for constants, using underscores to separate words.  For example, TAX_RATE.

 

Class, package and interface names:  Begin with a capital letter, and capitalize the first letter in each successive word.  For example  DataManager.

 

Variables and methods: Begin with a lower case, but capitalize the first letter in each successive word.  For example, setLimit, amountDue.

 

3.  Indentation:

When delimiting blocks of code with {}, these should appear alone on a line, lined up with the beginning of the line before the block.

Indent the code inside the block 3 spaces.

 

For example:

for (i = 0; i < n; i++)

{  

   j = j + 3 * i;

   sum = sum + j;

}

 

If the body of a conditional or loop consists of a single line, it should be indented on the line following the conditional or loop.  else should appear on the line following the closing brace of the if section.

 

 

if (x==0)

{

   System.out.println(“error condition”);

   err++;

}

else                    //  else should be lined up with if

   y = y + x;           //  indent on a new line

 

When an else if followed immediately by another if, put the else and if on the same line:

 

if (…)

{

 

}

else if (…)

{

 

}

else if (…)

{

 

}

etc…

 

Use spaces rather than tabs to indent, unless the tab can be set to convert to spaces.  Otherwise, the indentation may be incorrect when it is opened in another editor.  (Note: The automatic indentation provided with JCreator is acceptable, in most cases.)

 

4.  White space

Use blank lines to separate logical parts of the program.  For instance, use lines between the input of the data and the beginning of the computation.  Please limit consecutive blank lines to one or two.

 

Use spaces freely inside arithmetic expressions to make the operators easier to see.  For example, write x = 3 * (x + 4); or even x = 3 * ( x + 4 ); instead of x=3*(x+4);

 

5.  Predicates 

A predicate is the expression used in any conditional.  This includes if-then-else and all the looping constructs.  When constructing your conditional, keep it as simple as possible, separating unrelated relations into separate predicates.  For example,

 

if (x > 0 && x < 7)
   if ( n < 30)
   {  . . . }

instead of

if (x > 0 && x < 7 && n < 30)
{ . . . }

 

(Note: In the presence of else statements, single conditions and nested conditions may have different meanings.)

 

6. Get Methods and Set Methods

All class variables should be declared private or protected.  Get methods are used to read the value of the variables from outside the class while set methods are used to assign values to variables from outside the class. Such methods should begin with the word get (for accessing values) or set (for mutating values), followed by the name of the variable, which is capitalized:  getSize, setColor.