/[fenfire]/fenfire/docs/CodingConventions.rst
ViewVC logotype

Diff of /fenfire/docs/CodingConventions.rst

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 1.1 by tjl, Mon Sep 8 09:56:52 2003 UTC revision 1.2 by tjl, Mon Sep 8 10:01:24 2003 UTC
# Line 13  Rules Line 13  Rules
13  -----  -----
14    
15  - each Java file should contain the boilerplate copyright and  - each Java file should contain the boilerplate copyright and
16    license notice (see e.g. gzz/Cell.java).    license notice (see e.g. org/fenfire/Fen.java).
17    
18  - all of the classes should be in a package (under gzz).  - all of the classes should be in a package (under ``org.fenfire``).
19    
20  - 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.
21    Swing is not allowed    Swing is not allowed
22    The java.util Collections API    The java.util Collections API
23    (found in JDK 1.2, kaffe and as a separate download for 1.1)    (found in JDK 1.2, kaffe and as a separate download for 1.1)
24    IS allowed.    IS allowed. Java reflection and reference APIs are allowed.
25    
26    There is also Java/exp for experimental things that touch the core    ``org.fenfire.modules`` can depend on anything, as long as the dependency
27    which may depend on anything but shall not be compiled by default.    is documented.
28      Nothing in the main packages may depend on anything in the modules packages.
   Modules/ can depend on anything, as long as the dependency is documented.  
   Nothing in the main Java/ subdirectory may depend on anything in Modules/  
29    This ensures that we retain portability and easy installation. All the user    This ensures that we retain portability and easy installation. All the user
30    has to do is to give up on a module that has an odd dependency, not the whole    has to do is to give up on a module that has an odd dependency, not the whole
31    system.    system.
32    
   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.  
   
   
33    
34  - Each class should start with the line (not indented to save space)  - Each class should start with the line (not indented to save space)
35    
# Line 55  String rcsid = "$Id$"; Line 47  String rcsid = "$Id$";
47  - For debugging log messages, use the code  - For debugging log messages, use the code
48    
49      public static boolean dbg = false;      public static boolean dbg = false;
50      protected static void p(String s) { ZZLogger.log(s); }      protected static void p(String s) { System.out.println(s); }
51      ...      ...
52      if(dbg) p("Debug message");      if(dbg) p("Debug message");
53    
# Line 67  String rcsid = "$Id$"; Line 59  String rcsid = "$Id$";
59    and debugged logging. The former way used resources needlessly on    and debugged logging. The former way used resources needlessly on
60    every log message -- even if debugging was turned off.    every log message -- even if debugging was turned off.
61    
   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  
   
62  - Avoid both under- and overdocumenting.  - Avoid both under- and overdocumenting.
63    
 - 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.  
   
64  - Use anonymous classes freely  - Use anonymous classes freely
65    
66  - Try to keep the external APIs small, *with the exception* of providing  - Try to keep the external APIs small
   convenience routines for classes like ZZCell.  
67    
68  - Indenting: tabstop==8, shiftwidth == 4, cuddled braces, i.e.  - Indenting: tabstop==8, shiftwidth == 4, cuddled braces, i.e.
69                    
# Line 119  String rcsid = "$Id$"; Line 78  String rcsid = "$Id$";
78    however, you may use smaller shiftwidth if the function really really requires    however, you may use smaller shiftwidth if the function really really requires
79    it (although you should try to split it up).    it (although you should try to split it up).
80    
81  - for any more complicated functionality, feel free to start a new  - for any more complicated functionality, start a PEG.
   "white paper" -type documentation in the Documentation/ subdirectory.  
82    
83  - make your code such that it can be compiled in jikes +P (pedantic),  - make your code such that it can be compiled in jikes +P (pedantic),
84    JDK1.1.8 and JDK1.2.2 without warnings or errors.    JDK1.1.8 and JDK1.2.2 without warnings or errors.

Legend:
Removed from v.1.1  
changed lines
  Added in v.1.2

savannah-hackers-public@gnu.org
ViewVC Help
Powered by ViewVC 1.1.26