Aims

Coding Recommendations

Notes

Quite often we need to mark a place in the source-code in case we need to come back to it at some later date. The general format we use it like this:
TAG(user): message
Using a common format makes it easy for IDEs to pick them out. TAG is one of the TAGs in the list below. User is your username, and message is a the text of the message you need to make. The common tags we use at the moment are:

There are other tags, documented in tags.txt in the root of the jsword module.

Compiler Settings

If you want to know how to setup Eclipse to use the same compiler settings as we do then the following screenshots ought to help:

JDK Versions

The goal of Java is "write once, run anywhere." With regard to the JSword development, it means, "write once, anywhere." The practical impact of this is that JSword development community uses Linux, Windows and Mac. Thus, JSword needs to use the "lowest common denominator" of the JDK.

This is all currently being written using JDK 5. The basis for this is that (where practical) we will retain support for JDKs where some of our users have no better options.

Coding Standards

The coding standards used on this project so far are very much based on the SUN coding standards. This is some notes on style we are using, some of this deviates from the SUN standard, and some is just extensions to it.

Packaging

There is a split between classes that are specific to this project and those that could be usefully employed elsewhere. Generally we should:

Generalized code exists in org.crosswire. Code specific to this project lives in org.crosswire.jsword.

Also, since there is an Model-View-Controller (MVC) relationship between various parts of the code we avoid importing view code into model code, but model code is imported by both model and view code.

Also any code specific to an interface X should be in a package containing x. For example all swing specific code is in a *swing* package. This helps us in packaging code for a distribution, in excluding other interfaces.

Bracket Indentation

The "Sun Way" conserves screen space at the expense of readibility - which given the cost of decent size monitors these days seems silly. A lot of Java code, seems to ignore Sun and do it this way: 

if (something)
{
    func();
}

For those using Eclipse, a set of formatting rules for java code have been provided (etc/eclipse/jsword-format.xml). This can be loaded into Eclipse under Window->Preferences->Java->Code Formatter->Load.

Class Ordering

Variables are not important members of a class so why put them at the top? JSword usage puts them at the bottom.

Tabbing

4 space indents are a Good Thing, however using a tab character instead of 4 spaces just causes problems when you want to print, open in a different editor, or want to paste into an html doc using <pre> tags. Everything will look exactly the same if you use spaces instead of tabs.

Preamble

All java source should have the following at the end of the class JavaDoc

 * <p><table border='1' cellPadding='3' cellSpacing='0'>
 * <tr><td bgColor='white' class='TableRowColor'><font size='-7'>
 * Distribution License:<br />
 *
 * JSword is free software; you can redistribute it
 * and/or modify it under the terms of the GNU General Public License,
 * version 2 as published by the Free Software Foundation.<br />
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
 * General Public License for more details.<br />
 * The License is available on the internet
 * <a href='http://www.gnu.org/copyleft/gpl.html'>here</a>, or by writing to:
 * Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston,
 * MA 02111-1307, USA<br />
 * The copyright to this program is held by its authors.
 * </font></td></tr></table>
 * @see gnu.gpl.License
 * @author ...
 * @version $Id$

The result looks something like this from JavaDoc:


Distribution License:
JSword is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License, version 2 as published by the Free Software Foundation.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
The License is available on the internet here, or by writing to: Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA
The copyright to this program is held by its authors.

Similarity beween Java Sword API and C++ Sword API

The core Java API is similar in that there are concepts like Key, Verse etc in both. However there are differences; In Java Verse is stateless but the C++ SWVerse is stateful. For those wanting to write Java code using the C++ API there is an API compatibility tree (under development) that calls the core tree. This compatibility tree tries to mimic the C++ wherever possible.

The 2 APIs are not more similar to 2 reasons, one historic JSword was originally written under the name ProjectB, and only later merged into JSword. However there are a number of problems with language independant APIs. They all risk falling into the same traps as CORBA, DOM and SAX - all good examples of how *not* to write an API, and hence the need for RMI/EJB, JDOM/XOM/DOM4J/JAXB/etc.
An example for our case would be statefulness. Should the low level APIs for Verse etc be stateful? In C++/Sword they are, and there is sense for this in C++ because operator overloading makes incrementing a verse easy. Java however has a powerful concept of immutability that does not seem to be as important in C++, so a Java string is guaranteed not to change, where C++ lets you cast away any protection. Immutability lets us return values without cloning them, and be sure that they will not change, and it lets them have an ordering in a list that otherwise would be meaningless.