Hello,

Welcome on the Sashipa-Melba project.

Here are the rules for writing Java source code in the Sashipa-Melba project. They
are required (unless otherwise specified). It's necessary for programming in community.


*** Configure your editor ***

- In source code, the indent size is 2 spaces. Configure your editor. If possible,
  replace tabulations by spaces.


*** Java programming rules ***

- All Java programming rules are applied on this project.

- names in Java
  -> myVariable, myInstance
  -> myMethod
  -> MyClass
  -> mypackage
  -> MY_CONSTANT

- It's better (but this Java convention is not required on this project) that you don't 
  use an underscore for distinguishing an instance's variable from a parameter variable. 
  A solution:
  -> void setName(String name) { this.name = name; }


*** Sashipa-Melba programming rules - syntax ***

- Source code is written in english. Error messages in fatal exceptions are in
  english too. (multi-languages isn't managed for fatal errors)

- Open brace are at the end of the previous instruction:
  -> if (index == 2) {
  ->   instruction1;
  ->   instruction2;
  -> }

- It's good to use "this.myVariable" when you define a new value for an instance's
  variable. Even if it's not required for distinguishing an instance's variable from a
  parameter. It's easier to locate in the code where the object changes its state.

- Do not use a prefix for variable names. Except for booleans:
  -> int myInteger
  -> String myString
  -> char myCharacter
  -> boolean bMyBoolean


*** Sashipa-Melba programming rules - comments and code structure ***

- Javadoc-comment for public methods are advised, Javadoc-comment for interface's
  methods are required.

- About the code inside a method: make many blocks of code. Write a title for
  each block with a comment and a TIRET at the same level of indentation:
  -> // - work on lstForeignKey
  -> Iterator iter = lstForeignKey.listIterator();
  -> while (iter.hasNext()) // ...

- If you have too many indentation levels in a method, cut out the code to
  private methods called in loops. For giving an idea, 4 different indentation 
  levels into a method is very much.

- It's better when a method can be display in only one screen (without using lift).
  Cut up it to several method calls if necessary.

- It's better when a line of code doesn't be taller than the screen. Cut up too
  long strings and concatenate them on many lines if necessary.
  Example:
  -> myInstance.setTheMessageAndTheSize(
  ->   "MY VERY LONG VERY LONG VERY LONG VERY LONG LONG LONG LONG LONG LONG LONG " +
  ->   "LONG LONG HELLO\n\n\n\nWORLD !!!",
  ->   15
  -> );

- Variables, and more generally all non-public members, are declared at the end of
  the class. So public members are first.

- In a class, separate methods by blocks. Example:
  - a 'constant' block with the final static public constants.
  - an 'init' block with constructors and public methods for to customize the 
    instance.
  - a 'write' block with all public method that change the state of the object.
  - a 'read' block with all public method that don't change the state of the object.
  - If your class implements an interface or extends a class, put the implemented
    methods in a block named as the interface or the super-class.
  - a 'for sub-classes' block for protected methods.
  - a 'private' block for private methods.
  - a 'variables' block for the private variables.
  A block begin by a big comment like this:
  -> // ----------------------------------------------------------------------------
  -> // ------------------------------ variables -----------------------------------
  -> // ----------------------------------------------------------------------------

- An internal class is in a specific block too (except for anonymous classes):
  -> // ############################################################################
  -> // ################# internal class: KeyboardInputException ###################
  -> // ############################################################################


*** Sashipa-Melba programming rules - other rules ***

- Each instance's variable must be declared as private ! Private is private. It's
  not package neither protected or public.

- Declare method as 'protected' only if they are used by sub-classes. Otherwise,
  use 'private'. Do not anticipate futures sub-classes if you aren't completely
  sure that they will existing. (It's better to modify the super class when you need)

- When declaring an abstract class: in most of cases it's better to declare public
  and protected methods as 'final' (except when they are abstract, of course !).

- It's very exceptionally that a method can return null. For this category of methods,
  you have to put a javadoc-comment for signal when the null value can be returned.

- It's very exceptionally that a method accept a null parameter. For theses methods,
  you have to put a javadoc-comment for signal it.

- Each method can throw a FatalException. Constructors too.

- Do not use java.util.Vector , but java.util.ArrayList
- Do not use java.util.Hashtable , but java.util.HashMap

- If you use a hash-table (HashMap, HashSet, ...) then take care to methods
  equals(Object) and hashCode() in the classes of stored objects. See examples in
  melbaXXX.melbapacket.

- No problems with 'break' and 'continue' and infinite loops. This code is allowed:
  -> while(true) { /*...*/ if (cond) break; /*...*/ }


*** Others ***

- Think to programmers that will read your code later. Write easy-to-understand 
  code ! Do not keep an unemployed parameter. Put comments on each complex line 
  code. Always respect indentations, etc.. Read what you have written !

- Take example on the Database2Sashipa or Sashipa2Melba source code. Melba source
  code doesn't respect all of theses rules, because there are many very old source
  codes. You can fixe problems when you meet them :o)

- For any questions: thomas.mur@sashipamelba.com


Thomas


**

Vocabulary:

class MyClass {
  final public static int MY_CONSTANT = 3;
  public void myMethod(int myParameter) {}
  private int myInstanceVariable;
  private static int myClassVariable;
}