                         ------------------------------
                         -- CODING STANDARD ADDENDUM --
                         --   Revised May 28, 2006   --
                         ------------------------------

Addendum to Sun(tm) Coding Standard - http://java.sun.com/docs/codeconv/ 

9. Naming Convention:

   - All non-constant variables members start with underscore.
   
   
     class Foo {
     	int _value;
     	boolean _isReady;
     }
     
     Rationale: Prevents members from being overshadowed by parameters.
                Increases readability (makes "this." prefixing unnecessary).
                      
   - The first letter after the underscore is uppercase for static variables.
   
     class Foo {
     	static boolean _IsInitialized;
     	static FastTable<Foo> _Instances;
     }
     
     Rationale: Distinguishes static and non-static class variables.
   
   - Variable name for arrays or collections are plural.
        
     class Foo {
     	static Factory[] _Factories; // NOT: _FactoryArray
     	FastList<Foo> _children; // NOT: _childList
     }
     
     Rationale: Improves abstraction (and readability).

  - Acronyms -  Capitalize all letters except for leading acronyms of 
                variable names (all lower case).
     
     XMLStreamWriter createXMLStreamWriter();
     UTF8Stream utf8Stream;
   
     Rationale: Consistent with Standard Java Library (JDK).


10. Programming Practices:

   - Class prefixes for static method invocations (e.g. Factory.newId()).
   
     Rationale: Emphasizes that the method is static.
      
   - Consistent naming for factory methods: "valueOf", "newInstance" 
     or "getInstance".
   
     Rationale: Facilitates search (consistency).

   - null arguments are disallowed unless explicitly authorized:
   
     /** 
      * ...
      *
      * @param obj the object to add or <code>null</code>. 
      */

     Rationale: Reduces ambiguity (and comments).
   
   - If/else block statements enclosed with braces except for escape statements:
     
         if (!precondition)                if (obj == null) 
             throw new Exception();            return null;
         doSomething();                    doSomething();
         
     Rationale: Increases readability (reduces code).


12. Miscellaneous.

    Consider surrounding code examples with [code] and [\code]
    (in java source code and packages descriptions).

    /**
     * ...
     * Instances of this class can be used to resolve system of linear equations
     * involving <i>any kind</i> of {@link Field Field} elements. 
     * For example:[code]
     *     // Creates a matrix of complex elements.
     *     Complex[][] complexElements = ...;
     *     Matrix<Complex> M = Matrix.valueOf(complexElements);
     * [code]</p>
     */

    Rationale: Improve source code readability (avoid using escape sequences for 
    parameterized types). Allows for color coding of the examples by JavaDoc. 

    Note: Feature not yet supported by JavaDoc. Post-processing JavaDoc 
          utilities such as http://javolution.org/colapi.jar (public domain)
          can be used in the meantime.

----------------------------------------------------------
-- Copyright (C) 2006 - JScience (http://jscience.org/) --
-- All rights reserved.					                --
----------------------------------------------------------   				        