[Ijsql-devel] first cut at coding standards

[William G. <ww...@ts...>]

This is probably not complete, but let's get started deciding on this.

Note:
1) almost all of this is open for discussion.  If you disagree with any of
this, have additions, or have better ways of doing things, let's discuss it
on the list.
2) the initial code that I wrote doesn't necessarily follow all of these
rules, since I was writing it as a "one-off" app that I didn't think would
ever be used by anyone else.  Bad assumption on my part   ;-)      Part of
re-architecting the code will be to modify it to conform to the final coding
standards we agree on.

----------------------------------------

Naming
* Class Names - proper case
 example: " public class TestDbConnection "
* Method Names - lower case first portion, then uppercase the beginnings of
subsequent words
 example: " public String getDatabaseName "
* Variable Names - same format as method names, except for member variables,
covered next.
* Member Variable Names - prefixed with "m_"
 example: " private String m_dbName "

Braces & Indentation
* Braces on the line following the declaration, and indented to the same
spot
* Indent each new nesting level 4 spaces
* Convert tabs to spaces (I think most editors can be set to do this)

Exception handling
* Prefer to throw exceptions up to the top level, i.e., the presentation
layer.  Core code should basically be an api, and should not handle
exceptions itself.  There may be cases where the core code does need to
handle exceptions, and this should be decided on a case-by-case basis.

OO and Coding Philosophy
* Define interfaces for our classes.  Bind on these interfaces, rather than
on the concrete classes

* Challenge the existence of non-static member vars: are they only used in
one method? If so, they should probably be loval variables declared in that
method.

* There should be accessor (get / set) methods for any member vars that
require visibility outside the class itself.

* Try to keep method size down: if a method starts getting large and
convoluted, see if there are parts that stand alone, and can be extracted to
other methods.

* Prefer composition to inheritance: use the basic tests to determine which
to use: "is a" vs. "has a", etc.

* Javadoc your code, at the method and class level.  Use appropriate
comments throughout the code, without belaboring the obvious, i.e., you
don't need to do something like this:

    //load the value of the first column in the ResultSet into a temp string
    String tmp = rs.getString(1);

However, if there's some compelling reason that might not be obvious why
you're performing the operation, comment that.