[ff-cvs] fenfire/docs CodingConventions.rst

[Tuomas J. Lukka]

CVSROOT:        /cvsroot/fenfire
Module name:    fenfire
Branch:         
Changes by:     Tuomas J. Lukka <address@hidden>        03/09/08 06:01:25

Modified files:
        docs           : CodingConventions.rst 

Log message:
        Update for current conventions

CVSWeb URLs:
http://savannah.gnu.org/cgi-bin/viewcvs/fenfire/fenfire/docs/CodingConventions.rst.diff?tr1=1.1&tr2=1.2&r1=text&r2=text

Patches:
Index: fenfire/docs/CodingConventions.rst
diff -u fenfire/docs/CodingConventions.rst:1.1 
fenfire/docs/CodingConventions.rst:1.2
--- fenfire/docs/CodingConventions.rst:1.1      Mon Sep  8 05:56:52 2003
+++ fenfire/docs/CodingConventions.rst  Mon Sep  8 06:01:24 2003
@@ -13,39 +13,31 @@
 -----
 
 - each Java file should contain the boilerplate copyright and
-  license notice (see e.g. gzz/Cell.java).
+  license notice (see e.g. org/fenfire/Fen.java).
 
-- all of the classes should be in a package (under gzz).
+- all of the classes should be in a package (under ``org.fenfire``).
 
-- The main Java/ subdirectory may only depend on the JDK 1.1.8 APIs.
+- The main packages may only depend on the JDK APIs supported by Kaffe.
   Swing is not allowed
   The java.util Collections API
   (found in JDK 1.2, kaffe and as a separate download for 1.1)
-  IS allowed.
+  IS allowed. Java reflection and reference APIs are 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/
+  ``org.fenfire.modules`` can depend on anything, as long as the dependency 
+  is documented.
+  Nothing in the main packages may depend on anything in the modules packages.
   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: CodingConventions.rst,v 1.1 
2003/09/08 09:56:52 tjl Exp $";
+public static final String rcsid = "$Id: CodingConventions.rst,v 1.2 
2003/09/08 10:01:24 tjl Exp $";
 
   except interfaces, which should have
 
-String rcsid = "$Id: CodingConventions.rst,v 1.1 2003/09/08 09:56:52 tjl Exp 
$";
+String rcsid = "$Id: CodingConventions.rst,v 1.2 2003/09/08 10:01:24 tjl Exp 
$";
 
   instead.
 
@@ -55,7 +47,7 @@
 - For debugging log messages, use the code
 
     public static boolean dbg = false;
-    protected static void p(String s) { ZZLogger.log(s); }
+    protected static void p(String s) { System.out.println(s); }
     ...
     if(dbg) p("Debug message");
 
@@ -67,44 +59,11 @@
   and debugged logging. The former way used resources needlessly on
   every log message -- even if debugging was turned off.
 
-  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 Gzz. 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.
+- Try to keep the external APIs small
 
 - Indenting: tabstop==8, shiftwidth == 4, cuddled braces, i.e.
        
@@ -119,8 +78,7 @@
   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.
+- for any more complicated functionality, start a PEG.
 
 - make your code such that it can be compiled in jikes +P (pedantic),
   JDK1.1.8 and JDK1.2.2 without warnings or errors.