Source code: docs/WritingCode.java
1
2 package docs;
3
4 /**
5 Some hints, ideas and lesssons on coding for this project.
6
7 <h3>JDK Versions</h3>
8
9 <p>This is all currently being written in JDK 1.1 and not JDK 1.2.
10 1.1 has the advantage that it is available in more browsers and the MVM
11 that ships with IE4, Win95 OSR2.5, Win98 and WinNT is mostly JDK 1.1
12 compliant.
13 The things we are missing out on:<ul>
14 <li>Collections, Swing (which can be downloaded for 1.1 separately)</li>
15 <li>References, Classloader tweaks, Security (where we feel the pain)</li>
16 <li>Other improvments. (can easily live without them)</li>
17 </ul>
18 Currently I feel that platform availability is more important than the
19 problems mentioned above.
20 </p>
21
22 <h3>Momentum</h3>
23
24 <p>CatB talked about getting people involved -
25 "Release early and often", "Mailing Lists" and so on.
26 I plan to have a menu item "Get involved ..." This will present
27 a wizard thing to guide people to help. The ways of getting people
28 involved so far include:
29 <ul>
30 <li>Writing help files</li>
31 <li>Writing tips</li>
32 <li>Bug reports</li>
33 <li>Development requests/ideas</li>
34 <li>Packaging offers</li>
35 <li>Support/Mentoring other users</li>
36 <li>Creating a live lexicon</li>
37 <li>Reporting usage data</li>
38 </ul>
39
40 <h3>Coding Standards</h3>
41
42 <p>The coding standards used on this project so far are
43 very much based on the SUN coding standards. This is some notes on style we are
44 using, some of this deviates from the SUN standard, and some is just extensions
45 to it </p>
46
47 <h5>Packaging</h5>
48
49 <p>The is a split between classes that are specific to this project and those
50 that could be usefully employed elsewhere. Generally we should:
51 <ul>
52 <li>Make a much code general as possible</li>
53 <li>Only generalize where there is a point - specifically and code that does
54 something Bible specific should not be general</li>
55 <li>Never import specific code in generalized code</li>
56 </ul>
57 Generalized code exists in <code>org.crosswire</code>. Code specific to this
58 project lives in <code>org.crosswire.bible</code>.</p>
59
60 <p>Also, since there is an MVC relationship between various parts of the code
61 we avoid importing <code>org.crosswire.bible.view.*</code> in any other code,
62 and avoid importing <code>org.crosswire.bible.control.*</code> in anything but
63 <code>org.crosswire.bible.view.*</code></p>
64
65 <p>Also any code specific to an interface X should be in a package containing
66 x. For example all swing specific code is in a *swing* package. This helps us in
67 packaging code for a distribution, in excluding other interfaces.</p>
68
69 <h5>Bracket Indentation</h5>
70 <p>The "Sun Way" conserves screen space at the expense of readibility -
71 which given the cost of decent size monitors these days seems silly.
72 Most code I have seen, seems to ignore Sun and do it this way:<br>
73 <code>if (something)
74 <br>{
75 <br> func();
76 <br>}
77 </code></p>
78
79 <h5>Variable Naming</h5>
80 <p>Sun say use the same convention as for method names. I think this is
81 daft since it confuses method names and variable names. So I use
82 all lower case with underscores between words. I use word_count and not
83 wordCount. The Sun method makes some sense if you intend to use public
84 member variables, however that is generally not recommended behavior</p>
85
86 <h5>Class Ordering</h5>
87 <p>Variables are not important member of a class so why put them at the
88 top? I put them at the bottom.</p>
89
90 <h5>Tabbing</h5>
91 <p>A 4 space indents is a good thing, however using a tab character
92 instead of 4 spaces just causes problems when you want to print, open in
93 a different editor, or want to paste into an html doc using <pre>
94 tags. Everything will look exactly the same if you use spaces instead of
95 tabs.</p>
96
97 <h5>JavaDoc</h5>
98 <p>Is used extensively. I'm using the @version tag in a slightly
99 unconventional way to note the state of the class. A perfect class would
100 have an @version tag something like this <code>@version D9.I9.T9</code>.
101 In the real world, code like this will be rare.</p>
102 <ul>
103 <li>Documentation status is defined like: "Dn" where n means
104 - 0: no JavaDoc, 1: empty tags, 2-9 various degrees of
105 completeness</li>
106 <li>Test module status is defined like: "Tn" where n is a
107 number - 0: no test module, 1: module exists but doesn't work, 2-9:
108 varing degrees of completeness.</li>
109 <li>Visual inspection status: "In" where n means: 0: no
110 inspection to 9: thoroughly inspected.</li>
111 </ul>
112 <p>Another variation from the standard in the indentation which goes
113 something like:
114 <pre>
115 /**
116 * Stuff
117 *\
118 </pre>
119 I'm becoming unsure that this was originally a good idea - the original
120 justification was that it made indentation easier, however modern editors
121 make that untrue.</p>
122 <p>More importantly all the HTML markup in JavaDoc should be in XHTML
123 format so that it can be used in an XML engine.</p>
124
125 <h5>Code inclusion</h5>
126 <p>I am not excluding from the codebase code which I do not expect to be
127 in the final project - I think that we will need to consider how we do a
128 rollout, to get rid of the code that we never call. (the testing modules
129 could make automatic sortout more complex). My feeling now is - early
130 days, lets not get too harsh on amount of code in the codebase so long as
131 it is good quality.</p>
132
133 <h3>Lessons</h3>
134 <p><strong>XML</strong>: Where possible use DOM or SAX to access XML/XSL
135 implementations, where it is not possible separate the code into an
136 isolated class, and only do <code>import com.proprietoryvendor.xml.*;
137 </code> from within there.</p>
138
139 *
140 * <table border='1' cellPadding='3' cellSpacing='0' width="100%">
141 * <tr><td bgColor='white'class='TableRowColor'><font size='-7'>
142 * Distribution Licence:<br />
143 * Project B is free software; you can redistribute it
144 * and/or modify it under the terms of the GNU General Public License,
145 * version 2 as published by the Free Software Foundation.<br />
146 * This program is distributed in the hope that it will be useful,
147 * but WITHOUT ANY WARRANTY; without even the implied warranty of
148 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
149 * General Public License for more details.<br />
150 * The License is available on the internet
151 * <a href='http://www.gnu.org/copyleft/gpl.html'>here</a>, by writing to
152 * <i>Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston,
153 * MA 02111-1307, USA</i>, Or locally at the Licence link below.<br />
154 * The copyright to this program is held by it's authors.
155 * </font></td></tr></table>
156 * @see <a href='http://www.eireneh.com/servlets/Web'>Project B Home</a>
157 * @see <{docs.Licence}>
158 * @author Joe Walker
159 */
160 public class WritingCode { }