Docjar: A Java Source and Docuemnt Enginecom.*    java.*    javax.*    org.*    all    new    plug-in

Quick Search    Search Deep

docs
Class WritingCode  view WritingCode download WritingCode.java

java.lang.Object
  extended bydocs.WritingCode

public class WritingCode
extends java.lang.Object

Some hints, ideas and lesssons on coding for this project.

JDK Versions

This is all currently being written in JDK 1.1 and not JDK 1.2. 1.1 has the advantage that it is available in more browsers and the MVM that ships with IE4, Win95 OSR2.5, Win98 and WinNT is mostly JDK 1.1 compliant. The things we are missing out on:

Currently I feel that platform availability is more important than the problems mentioned above.

Momentum

CatB talked about getting people involved - "Release early and often", "Mailing Lists" and so on. I plan to have a menu item "Get involved ..." This will present a wizard thing to guide people to help. The ways of getting people involved so far include:

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

The 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.bible.

Also, since there is an MVC relationship between various parts of the code we avoid importing org.crosswire.bible.view.* in any other code, and avoid importing org.crosswire.bible.control.* in anything but org.crosswire.bible.view.*

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. Most code I have seen, seems to ignore Sun and do it this way:
if (something)
{
    func();
}

Variable Naming

Sun say use the same convention as for method names. I think this is daft since it confuses method names and variable names. So I use all lower case with underscores between words. I use word_count and not wordCount. The Sun method makes some sense if you intend to use public member variables, however that is generally not recommended behavior

Class Ordering

Variables are not important member of a class so why put them at the top? I put them at the bottom.

Tabbing

A 4 space indents is 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.

JavaDoc

Is used extensively. I'm using the @version tag in a slightly unconventional way to note the state of the class. A perfect class would have an @version tag something like this @version D9.I9.T9. In the real world, code like this will be rare.

Another variation from the standard in the indentation which goes something like:

/**
 Stuff
\
I'm becoming unsure that this was originally a good idea - the original justification was that it made indentation easier, however modern editors make that untrue.

More importantly all the HTML markup in JavaDoc should be in XHTML format so that it can be used in an XML engine.

Code inclusion

I am not excluding from the codebase code which I do not expect to be in the final project - I think that we will need to consider how we do a rollout, to get rid of the code that we never call. (the testing modules could make automatic sortout more complex). My feeling now is - early days, lets not get too harsh on amount of code in the codebase so long as it is good quality.

Lessons

XML: Where possible use DOM or SAX to access XML/XSL implementations, where it is not possible separate the code into an isolated class, and only do import com.proprietoryvendor.xml.*; from within there.

Distribution Licence:
Project B 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, by writing to Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA, Or locally at the Licence link below.
The copyright to this program is held by it's authors.


Constructor Summary
WritingCode()
           
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

WritingCode

public WritingCode()