Index: xdocs/code-standards.xml
===================================================================
RCS file: /home/cvspublic/jakarta-jetspeed/xdocs/code-standards.xml,v
retrieving revision 1.10
diff -u -r1.10 code-standards.xml
--- xdocs/code-standards.xml	16 May 2003 22:25:14 -0000	1.10
+++ xdocs/code-standards.xml	24 Jul 2003 17:33:16 -0000
@@ -316,24 +316,67 @@
 
     <section name="Logging">
     <p>
-      In general logging should be kept to a minimum.  Logging is very usefully 
-      for diagnosing and resolving problems.  Error message should describe the 
+      Logging is very useful for diagnosing and resolving problems. As a general rule, all exceptions should be logged, 
+      and done so in the following fashion: <br/>
+      <code>logger.error("What went wrong", ex);</code> <br/>
+      This way, both your message and a stack trace of the exception will be logged. Your error message should describe the 
       error, and where practical the cause and suggested solutions.
+      Do not log exceptions like this: <code>logger.error(ex);</code> Whenever you want to log a Throwable, it should be the 
+      second parameter of your fatal/error/warn/info/debug call. 
+    </p>
+    <p>
+      Since the new logging scheme uses Log4J, the penalty of log statements that are not actually activated, such as debug, 
+      is negligable. However, if your log message uses String concatenation ("+"), avoid loads of objects to be garbage collected by always 
+      checking if the particular level you are logging is enabled, by calling eg. <code>logger.isDebugEnabled()</code>. 
+      This is not necessary for logging simple Strings. Also, if you are building your message by concatenation, use 
+      StringBuffer and .append() instead of String and "+". Your code will be more efficient and produce less garbage.
     </p>
     <p>
       Debug logging is intended for development and problem determination.  It 
-      is not intended for use in a "normal" production environment.  In part 
-      because of the resource, including CPU and disk space, required.  So use
-      <code>Log.getLogger().isDebugEnabled()</code> to determine if debug 
-      logging is enable before generating the debug message.  
+      is not intended for use in a "normal" production environment. Therefore do not depend on important
+      information to be logged using debug. Do, however, add a reasonable about of debug logging in your code, expecially where 
+      robustness checks fail and "strange" things happen. This makes bug hunting a lot easier! <br/>
+      Do NOT use levels above debug, such as info, for debug messages!
+    </p>
+<source><![CDATA[
+if (logger.isDebugEnabled())
+{
+  StringBuffer msg = New StringBuffer("accessing rundata ");
+  mgs.append(m_runDataStore.get(Thread.currentThread());
+  msg.append(" for thread: ");
+  msg.append(Thread.currentThread());
+  logger.debug(msg.toString());
+}
+]]></source>
+    <p>
+      The following code snippet shows how to use the new logging features.
     </p>
 <source><![CDATA[
-if (Log.getLogger().isDebugEnabled())
+package mypackage;
+// The two imports needed
+import org.apache.jetspeed.services.logging.JetspeedLogFactoryService;
+import org.apache.jetspeed.services.logging.JetspeedLogger;
+
+class MyClass
 {
-  Log.debug("JetspeedRunDataService: accessing rundata "
-            + m_runDataStore.get(Thread.currentThread())
-            + " for thread: " + Thread.currentThread());
+    /**
+     * Static initialization of the logger for this class
+     */    
+    private static final JetspeedLogger logger = JetspeedLogFactoryService.getLogger(MyClass.class.getName());
+
+    /**
+     * Some method
+     */    
+     someMethod()
+     {
+     
+     	...
+     	logger.debug("This message should be logged");
+     
+     }
+    
 }
+
 ]]></source>
     </section>