123 lines
4.8 KiB
Plaintext
123 lines
4.8 KiB
Plaintext
Coding rules for GZigZag -*- Text -*-
|
|
========================
|
|
Tuomas Lukka
|
|
Antti-Juhani Kaijanaho
|
|
|
|
$Id: CODING,v 1.18 2001/03/08 15:05:12 tjl Exp $
|
|
|
|
This document attempts to give a brief guide on how to write
|
|
Java code for this project.
|
|
|
|
- each Java file should contain the boilerplate copyright and
|
|
license notice (see e.g. Java/ZZCell.java).
|
|
|
|
- all of the classes should be in a package. The packages are
|
|
org.gzigzag -- general core stuff
|
|
org.gzigzag.module -- modules
|
|
org.gzigzag.dimension -- dimensions for use with DimSpace
|
|
|
|
- The main Java/ subdirectory may only depend on the JDK 1.1.8 APIs.
|
|
Swing is not allowed.
|
|
|
|
There is also Java/exp for experimental things that touch the core
|
|
which may depend on anything but shall not be compiled by default.
|
|
|
|
Modules/ can depend on anything, as long as the dependency is documented.
|
|
Nothing in the main Java/ subdirectory may depend on anything in Modules/
|
|
This ensures that we retain portability and easy installation. All the user
|
|
has to do is to give up on a module that has an odd dependency, not the whole
|
|
system.
|
|
|
|
Note that all modules need not be in the Modules/ subdirectory: for instance,
|
|
the TextCloud module does not depend on anything beyond the core Java code
|
|
and may in the future be called by the core Java code so it is located in
|
|
the core subdirectory.
|
|
|
|
|
|
|
|
- Each class should start with the line (not indented to save space)
|
|
|
|
public static final String rcsid = "$Id: CODING,v 1.18 2001/03/08 15:05:12 tjl Exp $";
|
|
|
|
except interfaces, which should have
|
|
|
|
String rcsid = "$Id: CODING,v 1.18 2001/03/08 15:05:12 tjl Exp $";
|
|
|
|
instead.
|
|
|
|
This will pull in the version identifier from the CVS file.
|
|
XXX IT SHOULD PROBABLY BE INCLUDED IN THE JAVADOC AS WELL!
|
|
|
|
- For debugging log messages, use the code
|
|
|
|
public static boolean dbg = false;
|
|
protected static void p(String s) { if(dbg) ZZLogger.log(s); }
|
|
protected static void pa(String s) { ZZLogger.log(s); }
|
|
|
|
to print out messages. The System.out.println() is too verbose to insert
|
|
into code. This code can be added to the beginning of any class.
|
|
|
|
NOTE THE CHANGE FROM PREVIOUS: there is NO "final" qualifier for dbg,
|
|
as a non-final dbg can be used on the commandline to switch debugging
|
|
on at runtime, without a recompilation. Not all files have been changed yet.
|
|
|
|
NOTE THE CHANGE FROM PREVIOUS: We now use ZZLogger, allowing logging
|
|
the debug output into a file that can be sent to us in case of a
|
|
puzzling bug. This avoids having to have a scrollback buffer in
|
|
your terminal emulator.
|
|
|
|
NOTE THE CHANGE FROM PREVIOUS: there are NO "final" qualifiers for p and pa,
|
|
because they are unnecessary for static methods. p and pa are now private.
|
|
Not all files have been changed yet.
|
|
|
|
NOTE THE CHANGE FROM PREVIOUS: The methods are now protected; this allows
|
|
them to be used in subclasses. When they were private, debugging subclasses
|
|
was impossible. Not all files have been changed yet.
|
|
|
|
- If you want to kill the program, use SafeExit.exit instead of System.exit;
|
|
this allows consistent cleanup at exit time
|
|
|
|
- Avoid both under- and overdocumenting.
|
|
|
|
- Use Java 1.1.8: use of 1.2 features is allowable IF you carefully check
|
|
that the code works in 1.1.8, minus the features given by 1.2. So for
|
|
instance, if you make a cache that works with the garbage collector
|
|
interface in 1.2 to enable passive cleaning, the code should run on 1.1.8,
|
|
either without the cache, or without the cleaning (currently the ZZCellScroll
|
|
caches without any cleaning).
|
|
|
|
One of the considerations here is that Kaffe JVM provides a completely
|
|
free platform on which we can run the free GZigZag. If SUN or someone else
|
|
ever releases their Java implementation under a free license, the situation
|
|
is completely different.
|
|
|
|
- Use anonymous classes freely
|
|
|
|
- Try to keep the external APIs small, *with the exception* of providing
|
|
convenience routines for classes like ZZCell.
|
|
|
|
- Indenting: tabstop==8, shiftwidth == 4, cuddled braces, i.e.
|
|
|
|
public void method() {
|
|
if(...) {
|
|
...
|
|
} else {
|
|
...
|
|
}
|
|
}
|
|
|
|
however, you may use smaller shiftwidth if the function really really requires
|
|
it (although you should try to split it up).
|
|
|
|
- for any more complicated functionality, feel free to start a new
|
|
"white paper" -type documentation in the Documentation/ subdirectory.
|
|
|
|
- make your code such that it can be compiled in jikes +P (pedantic),
|
|
JDK1.1.8 and JDK1.2.2 without warnings or errors.
|
|
|
|
- as an aside, I really recommend using a coloring editor since there are
|
|
many points where significant sections have been commented out. This
|
|
is bad practice but inevitable in a system that doesn't easily allow
|
|
us to attach the sections which are not useful now but might be later
|
|
to the text in a xanadu-like manner.
|