|
|||||||||
| Home >> All >> [ docs overview ] | PREV CLASS NEXT CLASS | ||||||||
SUMMARY:  JAVADOC |  SOURCE |  DOWNLOAD | NESTED | FIELD | CONSTR | METHOD |
DETAIL: FIELD | CONSTR | METHOD | ||||||||
docs
Class WritingCode
java.lang.Objectdocs.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:
- Collections, Swing (which can be downloaded for 1.1 separately)
- References, Classloader tweaks, Security (where we feel the pain)
- Other improvments. (can easily live without them)
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:
- Writing help files
- Writing tips
- Bug reports
- Development requests/ideas
- Packaging offers
- Support/Mentoring other users
- Creating a live lexicon
- Reporting usage data
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:
- Make a much code general as possible
- Only generalize where there is a point - specifically and code that does something Bible specific should not be general
- Never import specific code in generalized code
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.
- Documentation status is defined like: "Dn" where n means - 0: no JavaDoc, 1: empty tags, 2-9 various degrees of completeness
- Test module status is defined like: "Tn" where n is a number - 0: no test module, 1: module exists but doesn't work, 2-9: varing degrees of completeness.
- Visual inspection status: "In" where n means: 0: no inspection to 9: thoroughly inspected.
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()
|
|||||||||
| Home >> All >> [ docs overview ] | PREV CLASS NEXT CLASS | ||||||||
|
SUMMARY: JAVADOC | SOURCE | DOWNLOAD | NESTED | FIELD | CONSTR | METHOD |
DETAIL: FIELD | CONSTR | METHOD | ||||||||