i-scream documentation viewer

coding_standards.txt

Coding Standards
================

tdb1, 28/11/20000


Document description
====================

The purpose of this document is to provide a defined
standard to which all code will conform. This will ensure
consistency across all files, and allow all members of the
team to easily follow the different pieces written by other
members.


Contents
========

 - Foreword
 
 - Structure & Layout
 
   - Identifiers
   - Final Variables
   - Indentation and Layout
   - Bracketing
   - Exceptions
   - Access Control
   - Imports
   - Overall Class Layout
 
 - Naming Conventions
 
 - Commenting & Documentation
 
   - Class and Interfaces
   - Methods
   - Attributes and Variables
   - General Commenting
 
 - General Recommendations
 
   - Threading
   - Class Design
   - Platform


Foreword
========

In constructing this document I have heavily used content
found in the following documents. I have tried to use these
documents to give our Coding Standard a solid foundation,
without doing a lot of unnecessary work that has already
been done by these authors.

The majority of this document is taken from the book by
David Barnes, with the other two just being used for small
parts which David hasn't covered in as much detail.

Java Stylistic Conventions, by David Barnes
  http://www.cs.kent.ac.uk/people/staff/djb/Book/style.html
Draft Java Coding Standard, by Doug Lea
  http://g.oswego.edu/dl/html/javaCodingStd.html
Netscape's Java Coding Standards Guide
  http://developer.netscape.com/docs  ...
                          ...  /technote/java/codestyle.html


Structure & Layout
==================

Identifiers
-----------

Identifiers can come down to simple imagination, and there
isn't a right or wrong way of doing it. The only restriction
is that they should be descriptive and of a reasonable
length. A variable name should have a single use and a name
fitting to this use, rather than using a single
non-descriptive name for multiple purposes.

A common convention is that names of methods, attributes,
and variables should begin with an initial lower-case letter
and have a single upper-case letter at the start of each new
word within the name. Class names should begin with an
uppercase letter and follow the same rule for the start of
each new word. Examples of these could be:

  myVariable
  aClassAttribute

  aUsefulMethod()

  CleverClassName

Accessor and Mutators should have names based on the
attribute to which they provide access. They should begin
with the prefix get or set followed by the name of the
attribute beginning with a capital letter. For example the
variable item would have the following accessor and mutator:

  getItem()
  setItem()

Variable names with a single character, such as x, should be
avoided as they convey little about their use. The only
exception to this rule is when it is used as a loop-control
variable in a for-loop. In this instance the variable serves
only as a counter, and this is obvious from it's use.

Method variables are those used within a method and should
be used in preference to an attribute if their use is to be
short. They should be defined as close to their use as
possible to make code easier to follow. Use should be made
of the fact that variables defined within nested blocks are
only visible within the block of code, and thus is only
visible to it's related code.

Final Variables
---------------

It is important to avoid the use of magic numbers within the
code. The main reason for this is that it can be hard to
identify which numbers should be changed if the use of the
program needs to be altered. Instead a final variable should
be defined in the program:

  private final int ST = 2;
  private final int E = 3;
  private final int S = 1;

The only time when magic numbers are acceptable is when they
are used as a variable initialiser or as a simple step.
Sometimes final variables are needed by more than one class,
in which case they should be defined as public static final
instead. These types of variables with public visibility
should be placed at the start of the class definition

Final variables should also have all upper-case names, thus
making them clearly identifiable over class attributes. The
use of the final word will also dictate that they cannot be
changed, so accessor's and mutator's are not necessary.

Indentation and Layout
----------------------

Lines should be kept to a sensible length to make the code
easier to read and print. Lines should be broken at a
sensible point and indented further than the current level
of identation. If space permits they should be lined up as
appropriate with the previous line:

  private static final byte[] packet = { Datatypes.FLAG,
                                         Datatypes.TERM,
                                         Datatypes.FLAG,
                                       };

Indentation should be four spaces for each level, and single
blank lines should be used to separate methods and to
emphasize blocks of code, as in this example:

  class MyExample {
     
      public int returnValue(int x){
          return x;
      }
  
  }

Methods should be defined first in a class, preferably in
order of visibility - public methods first, private ones
after. Attributes should be defined after methods for the
class, exception for public final variables which should be
defined first. This will be discussed further in Overall
Class Layout later on in this document.

Bracketing
----------

Brackets are very common in Java code and can be used
sensibly to clearly show the blocks of code they
encapsulate. An opening curly bracket that follows a class
header should be indented by a single space, but those used
after a method header should not. Closing curly brackets
should be placed on the line after the last line of the code
they enclose, at the same level of indentation as the start
of the header on which the block begins:

  class MyExample {
      public void method(){
          . . .
      }
  }

Curly brackets should always be used for if-, while- and
for-, even when not strictly needed - such as when the body
only contains a single statement. This is the correct way to
do it:

  if(x > largest){
      largest = x;
  }

Sometimes statements within normal brackets need to be
broken across several lines. This break should occur after
an operator and the next line should be indented further
than the code which will follow in the body.

Exceptions
----------

Exceptions should be used where necessary, and these should
almost always be checked exceptions. Instead of throwing the
basic Exception classes, sub-classes should be made with
more meaningful names, although they need not provide any
further functionality. Appropriate catch statements should
be put in place to allow the program to recover if need be.

Access Control
--------------

The following rules should be adhered to, ensuring that
access control is correctly implemented and used.

  - Attributes of an object should be declared as private,
    rather than public, package or protected. The only 
    exception is in the use of static final variables which 
    cannot be changed anyway.
    
  - Accessors may be used to grant access to attributes of a
    primitive type, although much more care must be taken 
    when returning references to attributes of object types 
    since this could lead to possible bypassing of any 
    mutators.
    
  - Mutators should be protected unless they specifically 
    need to be public. A mutator can ensure that values are 
    checked before being put in to the private attribute.
    
  - Methods commonly have public access, although private
    access should be considered if the method is to be used 
    only by the class in which it is placed.
    
  - Package visibility should also be considered if the use 
    of packages is implemented. Again, each method's use 
    should be considered carefully, and an appropriate 
    access control method chosen.
    
  - Protected visibility is unlikely to be used as sub-
    classing any of the classes is unlikely, although if
    such a situation should arise it should be carefully
    considered.

When considering what type of access control to use it is
best to be more restrictive than lenient. If a method's
visibility is too restrictive then it will be identified
more quickly than if the reverse were to happen.

Imports
-------

The use if the * form of import should be avoided. Each
class should be specifically imported as required, and any
unused imports should be removed if they are no longer
needed. This makes it clear as to exactly what the class is
using.


Overall Class Layout
--------------------

The overall layout of a class is important, especially when
it comes to reviewing the code at a later stage. Here I will
outline the order in which methods and attributes should
appear in a class. This psuedo class shows where everything
should appear, including imports and package declarations.
Commenting will be dealt with in a further section.

  // package declaration
  package server
  // imports
  import java.util.LinkedList
  import java.io.InputStream
  
  class MyDummyClass {
  
      // attributes such as "magic numbers" should be first
      public static final int S = 1;
      public static final int E = 3;
  
      // no-args constructor first
      public MyDummyClass(){
          . . .
      }
  
      // further constructors follow
      public MyDummyClass(int x){
          . . .
      }
  
      // public methods
      public void myMethod(){
          . . .
      }
  
      // private methods
      private void anotherMethod(){
          . . .
      }
  
      // accessors & mutators
      public int getMyVar(){
          . . .
      }
  
      // private attributes
      private int myVar = 5;
  }

This layout should be followed in every source file
generated. The reason for this structure is that reading
downwards you reach the most used methods and attributes
first. The exception are the public static final attributes
which are put first to allow them to easily be identified
and changed at a later date.

Naming Conventions
------------------

Although this section has been covered throughout the last
section, I think it is key that the various naming
conventions be clearly identified here. Examples are given
for each convention.

  - Packages
      eg. demo.package
      Package names should all be in lower case.
  
  - Files
      eg. ClassName.java
      The Java convention is that files have the same name 
      as the class they contain, and the compiler enforces 
      this.
  
  - Classes
      eg. ClassName
      Class names should begin with a capital letter and 
      each new word within the name should begin with a 
      capital letter.

  - Exception Classes
      eg. ClassNameException
      Exception classes should follow the same rule as 
      normal classes, but should end with the word 
      Exception.

  - Constants or "magic numbers" (public)
      eg. MY_STATIC_VARIABLE
      These public static variables should always be in
      upper-case. An underscore could be used if required to 
      make the name more readable.

  - Methods
      eg. methodName()
      Methods should begin with a lower case letter and each 
      new word within the name should begin with a capital 
      letter.

  - Variables and Attributes
      eg. variableName
      Both variables and attributes should being with a 
      lower case letter and each new word within the name 
      should begin with a capital letter - exactly the same 
      as methods.

  - Accessors
      eg. getVariable()
      Accessors should follow the same rules as a normal 
      method, but should be named after the variable which 
      they provide access to.

  - Mutators
      eg. setVariable(...)
      Mutators should follow the same rules as a normal 
      method, but should be named after the variable to 
      which they control access.


Commenting & Documentation
==========================

All programs should be properly and thoroughly documented.
The javadoc tool provides a convention for documenting code
and facilitates the automatic generation of program
documentation.

Classes and Interfaces
----------------------

Each class should have a javadoc comment block at the start
of the code. This block of comment should be placed in the
standard javadoc style /** .. **/ immediately preceding the
class header. Package declarations and imports will appear
before this initial documentation. Within this section the
following items should be included:

  - Class Name
  - Description of the class and it's use
  - Revision History
  - Author(s) - javadoc tag
  - Version Number - javadoc tag

It is important to note that as well as the code being read
by hand, these comments will also be used to generate
information about the class on a webpage using javadoc.
Bearing this in mind it may be necessary to use HTML tags to
layout the comments, although these should be neatly done so
as not to make the comments unreadable in the source code.

Various javadoc tags should be used to give specific
information to the javadoc engine. These should be placed on
a separate line.

  - @author <author name>
    The name of the author, preferably with e-mail address.
    
  - @version <version number>
    The version number of the code, with date.

This is an example of a class header, which contains all of
the above items.

  /**
   * MyClass <br>
   *
   * This class is merely for illustrative purposes. <br>
   *
   * Revision History:<br>
   * 1.1 - Added javadoc headers <br>
   * 1.0 - Original release<br>
   *
   * @author T.D.Bishop
   * @version 1.1, 19/04/2000
   */
  public class MyClass {
      . . .
  }

Methods
-------

Methods should contain a similar javadoc comment to classes,
which should be places between /** .. **/ marks immediately
preceding the method header. It may not be necessary to do
this for all methods, but constructors and major methods
certainly should have them, whilst accessors and mutators
can have a more cut down version. The following items should
be included:

  - Purpose of method
  - Argument descriptions
  - Result descriptions
  - Exceptions thrown

There are also javadoc tags that can be used specifically
for method comments. In a similar way to class comments each
begins with an @ and should be placed on a line of it's own.

  - @param <param name> <param description>
    Should be specified for each parameter that a method 
    takes, with it's name and purpose.
    
  - @return <description>
    Describes the result returned by the method.
    
  - @throws <exception name> <reason for being thrown>
    Gives the name of any exceptions that may be thrown, and
    why.

Here is an example of a method header, showing the above in
use.

  /**
   * This method has no use, and it just illustrative. <br>
   * Although it does suggest adding the two parameters
   * together ! <br>
   *
   * @param first The first number to be added
   * @param second The second number to be added
   * @return The sum of the two parameters
   * @throws BadException if something goes very wrong !
   */
  public int sumNumbers(int first, int second) throws
  BadException{
      . . .
  }

Attributes and Variables
------------------------

Attributes and variables require far less commenting than
classes and methods. They should simply contain a brief
description of what they are used for, and could possibly
refer to any accessors or mutators that allow access to
them. Attributes that are public static final should have a
bit more detailed information as other classes may wish to
use them. Here is a basic example:

  /**
   * This attribute represents the byte value used to start
   * a packet.
   */
  public static final int ST = 2;


General Commenting
------------------

It is often necessary to add comments within the body of a
method. It is preferable to comment in blocks, rather than
individually on each line. Likewise it is not necessary to
comment code that is obvious in it's purpose. Both single
line comments (using //) and multi-line comments (using /*
.. */) are acceptable. This is an example of the layout of
the two methods:

  int index = 1; // index of starting point
  
  /* This is a mult-line
   * comment, and spans
   * several lines !
   */


General Recommendations
=======================

Threading
---------

Threading is a complicated issue, so I will only briefly
mention it. The main issue is using the synchronized
modifier to prevent deadlock over the system when accessing
shared objects. It is important not to overuse this, as it
can cause unnecessary deadlock. Use it only when there is a
clear need to do so.

Class Design
------------

Class design should be done in a way that reduces coupling
as far as possible. Simply dividing the overall system into
clear defined parts is a good way to start this.

Platform
--------

This document refers to the Java 2 platform (or JDK 1.2).
Everything mentioned in this document is based upon this
platform and may therefore be out of date in future versions
of the Java platform.