[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/09 08:15:28

Modified files:
        docs           : CodingConventions.rst 

Log message:
        Arch commit: more coding conventions

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

Patches:
Index: fenfire/docs/CodingConventions.rst
diff -u fenfire/docs/CodingConventions.rst:1.2 
fenfire/docs/CodingConventions.rst:1.3
--- fenfire/docs/CodingConventions.rst:1.2      Mon Sep  8 06:01:24 2003
+++ fenfire/docs/CodingConventions.rst  Tue Sep  9 08:15:28 2003
@@ -12,6 +12,8 @@
 Rules
 -----
 
+Rules are obligatory for code included in fenfire
+
 - each Java file should contain the boilerplate copyright and
   license notice (see e.g. org/fenfire/Fen.java).
 
@@ -33,18 +35,18 @@
 
 - Each class should start with the line (not indented to save space)
 
-public static final String rcsid = "$Id: CodingConventions.rst,v 1.2 
2003/09/08 10:01:24 tjl Exp $";
+public static final String rcsid = "$Id: CodingConventions.rst,v 1.3 
2003/09/09 12:15:28 tjl Exp $";
 
   except interfaces, which should have
 
-String rcsid = "$Id: CodingConventions.rst,v 1.2 2003/09/08 10:01:24 tjl Exp 
$";
+String rcsid = "$Id: CodingConventions.rst,v 1.3 2003/09/09 12:15:28 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
+- For debugging log messages, use code like
 
     public static boolean dbg = false;
     protected static void p(String s) { System.out.println(s); }
@@ -53,11 +55,9 @@
 
   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.
+  Debugging can then be turned on like ::
 
-  NOTE THE CHANGE FROM PREVIOUS: due to Java's handling of certain String
-  concenations, we now prefer not to use separate methods for non-debugged
-  and debugged logging. The former way used resources needlessly on
-  every log message -- even if debugging was turned off.
+    make run_fenpdfdemo DBG="-d org.fenfire.foobar.Foo
 
 - Avoid both under- and overdocumenting.
 
@@ -82,6 +82,51 @@
 
 - make your code such that it can be compiled in jikes +P (pedantic),
   JDK1.1.8 and JDK1.2.2 without warnings or errors.
+
+Conventions
+-----------
+
+Conventions are less absolute than rules - they are allowed to be broken
+but usually it's good form to follow them.
+
+Imports
+"""""""
+
+- Import first the most generic packages (i.e. java.util, ...), then 
+  the more specific ones (i.e. neighbouring package &c)
+
+- avoid importing * unless there is a reason (note: a reason, not a *good*
+  reason)
+
+- In jython, don't import too much. It's preferable to do ::
+
+    import vob
+    from org import fenfire as ff
+
+  and then use, e.g. ``ff.swamp.Nodes``, `ff.Fen`` &c. 
+  Jython is a weakly typed and soft language so it's much better to give
+  the reader a little more context.
+
+Variable names
+""""""""""""""
+
+- Avoid single-letter variable names, except for obvious cases such as
+  loop indices or coordinates.
+
+- If there's exactly one object of a given class that's relevant in
+  a certain method, name the variable decapitalized. This is *especially*
+  important in Jython, where code can get really hard to read.
+
+  It's sometimes hard to resist the temptation to abbreviate the name
+  but remember: **ALL** the time you win that way someone else (or you) will
+  lose later multiple times when trying to read the code.
+  See also the Tips section below for why abbreviations are not needed.
+
+Documenting
+"""""""""""
+
+- At the very least, document data! Document data members of classes,
+  especially in Jython.
 
 Tips (for speeding up work)
 ---------------------------