documentation/specification/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.ukc.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.

Revision:	1.1
Committed:	Tue Nov 28 00:14:21 2000 UTC (23 years, 5 months ago) by tdb
Content type:	text/plain
Branch:	MAIN
CVS Tags:	PROJECT_COMPLETION
Log Message:	Basic draft of the coding standards. DOC -> TXT from a previous document.
#	User	Rev	Content
1	tdb	1.1	Coding Standards
2			================
3
4			tdb1, 28/11/20000
5
6
7			Document description
8			====================
9
10			The purpose of this document is to provide a defined
11			standard to which all code will conform. This will ensure
12			consistency across all files, and allow all members of the
13			team to easily follow the different pieces written by other
14			members.
15
16
17			Contents
18			========
19
20			- Foreword
21
22			- Structure & Layout
23
24			- Identifiers
25			- Final Variables
26			- Indentation and Layout
27			- Bracketing
28			- Exceptions
29			- Access Control
30			- Imports
31			- Overall Class Layout
32
33			- Naming Conventions
34
35			- Commenting & Documentation
36
37			- Class and Interfaces
38			- Methods
39			- Attributes and Variables
40			- General Commenting
41
42			- General Recommendations
43
44			- Threading
45			- Class Design
46			- Platform
47
48
49			Foreword
50			========
51
52			In constructing this document I have heavily used content
53			found in the following documents. I have tried to use these
54			documents to give our Coding Standard a solid foundation,
55			without doing a lot of unnecessary work that has already
56			been done by these authors.
57
58			The majority of this document is taken from the book by
59			David Barnes, with the other two just being used for small
60			parts which David hasn't covered in as much detail.
61
62			Java Stylistic Conventions, by David Barnes
63			http://www.cs.ukc.ac.uk/people/staff/djb/Book/style.html
64			Draft Java Coding Standard, by Doug Lea
65			http://g.oswego.edu/dl/html/javaCodingStd.html
66			Netscape's Java Coding Standards Guide
67			http://developer.netscape.com/docs ...
68			... /technote/java/codestyle.html
69
70
71			Structure & Layout
72			==================
73
74			Identifiers
75			-----------
76
77			Identifiers can come down to simple imagination, and there
78			isn't a right or wrong way of doing it. The only restriction
79			is that they should be descriptive and of a reasonable
80			length. A variable name should have a single use and a name
81			fitting to this use, rather than using a single
82			non-descriptive name for multiple purposes.
83
84			A common convention is that names of methods, attributes,
85			and variables should begin with an initial lower-case letter
86			and have a single upper-case letter at the start of each new
87			word within the name. Class names should begin with an
88			uppercase letter and follow the same rule for the start of
89			each new word. Examples of these could be:
90
91			myVariable
92			aClassAttribute
93
94			aUsefulMethod()
95
96			CleverClassName
97
98			Accessor and Mutators should have names based on the
99			attribute to which they provide access. They should begin
100			with the prefix get or set followed by the name of the
101			attribute beginning with a capital letter. For example the
102			variable item would have the following accessor and mutator:
103
104			getItem()
105			setItem()
106
107			Variable names with a single character, such as x, should be
108			avoided as they convey little about their use. The only
109			exception to this rule is when it is used as a loop-control
110			variable in a for-loop. In this instance the variable serves
111			only as a counter, and this is obvious from it's use.
112
113			Method variables are those used within a method and should
114			be used in preference to an attribute if their use is to be
115			short. They should be defined as close to their use as
116			possible to make code easier to follow. Use should be made
117			of the fact that variables defined within nested blocks are
118			only visible within the block of code, and thus is only
119			visible to it's related code.
120
121			Final Variables
122			---------------
123
124			It is important to avoid the use of magic numbers within the
125			code. The main reason for this is that it can be hard to
126			identify which numbers should be changed if the use of the
127			program needs to be altered. Instead a final variable should
128			be defined in the program:
129
130			private final int ST = 2;
131			private final int E = 3;
132			private final int S = 1;
133
134			The only time when magic numbers are acceptable is when they
135			are used as a variable initialiser or as a simple step.
136			Sometimes final variables are needed by more than one class,
137			in which case they should be defined as public static final
138			instead. These types of variables with public visibility
139			should be placed at the start of the class definition
140
141			Final variables should also have all upper-case names, thus
142			making them clearly identifiable over class attributes. The
143			use of the final word will also dictate that they cannot be
144			changed, so accessor's and mutator's are not necessary.
145
146			Indentation and Layout
147			----------------------
148
149			Lines should be kept to a sensible length to make the code
150			easier to read and print. Lines should be broken at a
151			sensible point and indented further than the current level
152			of identation. If space permits they should be lined up as
153			appropriate with the previous line:
154
155			private static final byte[] packet = { Datatypes.FLAG,
156			Datatypes.TERM,
157			Datatypes.FLAG,
158			};
159
160			Indentation should be four spaces for each level, and single
161			blank lines should be used to separate methods and to
162			emphasize blocks of code, as in this example:
163
164			class MyExample {
165
166			public int returnValue(int x){
167			return x;
168			}
169
170			}
171
172			Methods should be defined first in a class, preferably in
173			order of visibility - public methods first, private ones
174			after. Attributes should be defined after methods for the
175			class, exception for public final variables which should be
176			defined first. This will be discussed further in Overall
177			Class Layout later on in this document.
178
179			Bracketing
180			----------
181
182			Brackets are very common in Java code and can be used
183			sensibly to clearly show the blocks of code they
184			encapsulate. An opening curly bracket that follows a class
185			header should be indented by a single space, but those used
186			after a method header should not. Closing curly brackets
187			should be placed on the line after the last line of the code
188			they enclose, at the same level of indentation as the start
189			of the header on which the block begins:
190
191			class MyExample {
192			public void method(){
193			. . .
194			}
195			}
196
197			Curly brackets should always be used for if-, while- and
198			for-, even when not strictly needed - such as when the body
199			only contains a single statement. This is the correct way to
200			do it:
201
202			if(x > largest){
203			largest = x;
204			}
205
206			Sometimes statements within normal brackets need to be
207			broken across several lines. This break should occur after
208			an operator and the next line should be indented further
209			than the code which will follow in the body.
210
211			Exceptions
212			----------
213
214			Exceptions should be used where necessary, and these should
215			almost always be checked exceptions. Instead of throwing the
216			basic Exception classes, sub-classes should be made with
217			more meaningful names, although they need not provide any
218			further functionality. Appropriate catch statements should
219			be put in place to allow the program to recover if need be.
220
221			Access Control
222			--------------
223
224			The following rules should be adhered to, ensuring that
225			access control is correctly implemented and used.
226
227			- Attributes of an object should be declared as private,
228			rather than public, package or protected. The only
229			exception is in the use of static final variables which
230			cannot be changed anyway.
231
232			- Accessors may be used to grant access to attributes of a
233			primitive type, although much more care must be taken
234			when returning references to attributes of object types
235			since this could lead to possible bypassing of any
236			mutators.
237
238			- Mutators should be protected unless they specifically
239			need to be public. A mutator can ensure that values are
240			checked before being put in to the private attribute.
241
242			- Methods commonly have public access, although private
243			access should be considered if the method is to be used
244			only by the class in which it is placed.
245
246			- Package visibility should also be considered if the use
247			of packages is implemented. Again, each method's use
248			should be considered carefully, and an appropriate
249			access control method chosen.
250
251			- Protected visibility is unlikely to be used as sub-
252			classing any of the classes is unlikely, although if
253			such a situation should arise it should be carefully
254			considered.
255
256			When considering what type of access control to use it is
257			best to be more restrictive than lenient. If a method's
258			visibility is too restrictive then it will be identified
259			more quickly than if the reverse were to happen.
260
261			Imports
262			-------
263
264			The use if the * form of import should be avoided. Each
265			class should be specifically imported as required, and any
266			unused imports should be removed if they are no longer
267			needed. This makes it clear as to exactly what the class is
268			using.
269
270
271			Overall Class Layout
272			--------------------
273
274			The overall layout of a class is important, especially when
275			it comes to reviewing the code at a later stage. Here I will
276			outline the order in which methods and attributes should
277			appear in a class. This psuedo class shows where everything
278			should appear, including imports and package declarations.
279			Commenting will be dealt with in a further section.
280
281			// package declaration
282			package server
283			// imports
284			import java.util.LinkedList
285			import java.io.InputStream
286
287			class MyDummyClass {
288
289			// attributes such as "magic numbers" should be first
290			public static final int S = 1;
291			public static final int E = 3;
292
293			// no-args constructor first
294			public MyDummyClass(){
295			. . .
296			}
297
298			// further constructors follow
299			public MyDummyClass(int x){
300			. . .
301			}
302
303			// public methods
304			public void myMethod(){
305			. . .
306			}
307
308			// private methods
309			private void anotherMethod(){
310			. . .
311			}
312
313			// accessors & mutators
314			public int getMyVar(){
315			. . .
316			}
317
318			// private attributes
319			private int myVar = 5;
320			}
321
322			This layout should be followed in every source file
323			generated. The reason for this structure is that reading
324			downwards you reach the most used methods and attributes
325			first. The exception are the public static final attributes
326			which are put first to allow them to easily be identified
327			and changed at a later date.
328
329			Naming Conventions
330			------------------
331
332			Although this section has been covered throughout the last
333			section, I think it is key that the various naming
334			conventions be clearly identified here. Examples are given
335			for each convention.
336
337			- Packages
338			eg. demo.package
339			Package names should all be in lower case.
340
341			- Files
342			eg. ClassName.java
343			The Java convention is that files have the same name
344			as the class they contain, and the compiler enforces
345			this.
346
347			- Classes
348			eg. ClassName
349			Class names should begin with a capital letter and
350			each new word within the name should begin with a
351			capital letter.
352
353			- Exception Classes
354			eg. ClassNameException
355			Exception classes should follow the same rule as
356			normal classes, but should end with the word
357			Exception.
358
359			- Constants or "magic numbers" (public)
360			eg. MY_STATIC_VARIABLE
361			These public static variables should always be in
362			upper-case. An underscore could be used if required to
363			make the name more readable.
364
365			- Methods
366			eg. methodName()
367			Methods should begin with a lower case letter and each
368			new word within the name should begin with a capital
369			letter.
370
371			- Variables and Attributes
372			eg. variableName
373			Both variables and attributes should being with a
374			lower case letter and each new word within the name
375			should begin with a capital letter - exactly the same
376			as methods.
377
378			- Accessors
379			eg. getVariable()
380			Accessors should follow the same rules as a normal
381			method, but should be named after the variable which
382			they provide access to.
383
384			- Mutators
385			eg. setVariable(...)
386			Mutators should follow the same rules as a normal
387			method, but should be named after the variable to
388			which they control access.
389
390
391			Commenting & Documentation
392			==========================
393
394			All programs should be properly and thoroughly documented.
395			The javadoc tool provides a convention for documenting code
396			and facilitates the automatic generation of program
397			documentation.
398
399			Classes and Interfaces
400			----------------------
401
402			Each class should have a javadoc comment block at the start
403			of the code. This block of comment should be placed in the
404			standard javadoc style / .. / immediately preceding the
405			class header. Package declarations and imports will appear
406			before this initial documentation. Within this section the
407			following items should be included:
408
409			- Class Name
410			- Description of the class and it's use
411			- Revision History
412			- Author(s) - javadoc tag
413			- Version Number - javadoc tag
414
415			It is important to note that as well as the code being read
416			by hand, these comments will also be used to generate
417			information about the class on a webpage using javadoc.
418			Bearing this in mind it may be necessary to use HTML tags to
419			layout the comments, although these should be neatly done so
420			as not to make the comments unreadable in the source code.
421
422			Various javadoc tags should be used to give specific
423			information to the javadoc engine. These should be placed on
424			a separate line.
425
426			- @author <author name>
427			The name of the author, preferably with e-mail address.
428
429			- @version <version number>
430			The version number of the code, with date.
431
432			This is an example of a class header, which contains all of
433			the above items.
434
435			/**
436			* MyClass <br>
437			*
438			* This class is merely for illustrative purposes. <br>
439			*
440			* Revision History:<br>
441			* 1.1 - Added javadoc headers <br>
442			* 1.0 - Original release<br>
443			*
444			* @author T.D.Bishop
445			* @version 1.1, 19/04/2000
446			*/
447			public class MyClass {
448			. . .
449			}
450
451			Methods
452			-------
453
454			Methods should contain a similar javadoc comment to classes,
455			which should be places between / .. / marks immediately
456			preceding the method header. It may not be necessary to do
457			this for all methods, but constructors and major methods
458			certainly should have them, whilst accessors and mutators
459			can have a more cut down version. The following items should
460			be included:
461
462			- Purpose of method
463			- Argument descriptions
464			- Result descriptions
465			- Exceptions thrown
466
467			There are also javadoc tags that can be used specifically
468			for method comments. In a similar way to class comments each
469			begins with an @ and should be placed on a line of it's own.
470
471			- @param <param name> <param description>
472			Should be specified for each parameter that a method
473			takes, with it's name and purpose.
474
475			- @return <description>
476			Describes the result returned by the method.
477
478			- @throws <exception name> <reason for being thrown>
479			Gives the name of any exceptions that may be thrown, and
480			why.
481
482			Here is an example of a method header, showing the above in
483			use.
484
485			/**
486			* This method has no use, and it just illustrative. <br>
487			* Although it does suggest adding the two parameters
488			* together ! <br>
489			*
490			* @param first The first number to be added
491			* @param second The second number to be added
492			* @return The sum of the two parameters
493			* @throws BadException if something goes very wrong !
494			*/
495			public int sumNumbers(int first, int second) throws
496			BadException{
497			. . .
498			}
499
500			Attributes and Variables
501			------------------------
502
503			Attributes and variables require far less commenting than
504			classes and methods. They should simply contain a brief
505			description of what they are used for, and could possibly
506			refer to any accessors or mutators that allow access to
507			them. Attributes that are public static final should have a
508			bit more detailed information as other classes may wish to
509			use them. Here is a basic example:
510
511			/**
512			* This attribute represents the byte value used to start
513			* a packet.
514			*/
515			public static final int ST = 2;
516
517
518			General Commenting
519			------------------
520
521			It is often necessary to add comments within the body of a
522			method. It is preferable to comment in blocks, rather than
523			individually on each line. Likewise it is not necessary to
524			comment code that is obvious in it's purpose. Both single
525			line comments (using //) and multi-line comments (using /*
526			.. */) are acceptable. This is an example of the layout of
527			the two methods:
528
529			int index = 1; // index of starting point
530
531			/* This is a mult-line
532			* comment, and spans
533			* several lines !
534			*/
535
536
537			General Recommendations
538			=======================
539
540			Threading
541			---------
542
543			Threading is a complicated issue, so I will only briefly
544			mention it. The main issue is using the synchronized
545			modifier to prevent deadlock over the system when accessing
546			shared objects. It is important not to overuse this, as it
547			can cause unnecessary deadlock. Use it only when there is a
548			clear need to do so.
549
550			Class Design
551			------------
552
553			Class design should be done in a way that reduces coupling
554			as far as possible. Simply dividing the overall system into
555			clear defined parts is a good way to start this.
556
557			Platform
558			--------
559
560			This document refers to the Java 2 platform (or JDK 1.2).
561			Everything mentioned in this document is based upon this
562			platform and may therefore be out of date in future versions
563			of the Java platform.
564