vmote       2003/07/01 11:40:26

  Modified:    src/documentation/content/xdocs/dev conventions.xml
  Log:
  Move some of the resolved "style" wiki contents to conventions.xml.
  
  Revision  Changes    Path
  1.2       +62 -4     xml-fop/src/documentation/content/xdocs/dev/conventions.xml
  
  Index: conventions.xml
  ===================================================================
  RCS file: /home/cvs/xml-fop/src/documentation/content/xdocs/dev/conventions.xml,v
  retrieving revision 1.1
  retrieving revision 1.2
  diff -u -r1.1 -r1.2
  --- conventions.xml   1 Jul 2003 17:24:34 -0000       1.1
  +++ conventions.xml   1 Jul 2003 18:40:26 -0000       1.2
  @@ -12,7 +12,7 @@
           <title>Java Style</title>
           <p>In order to facilitate the human reading of FOP source code, the FOP 
developers have agreed on a set of coding conventions.
   The basis of these coding conventions is documented in the <link 
href="http://xml.apache.org/source.html";>Apache XML Project Guidelines</link>, which 
requires that <strong>all Java Language source code in the repository must be written 
in conformance to Sun's</strong> <link 
href="http://java.sun.com/docs/codeconv/html/CodeConvTOC.doc.html";>Code Conventions 
for the Java Programming Language</link>.
  -In addition, other conventions have been applied to the FOP project, which are 
summarized in the following table:</p>
  +In addition, the FOP developers have agreed to other conventions, which are 
summarized in the following table:</p>
           <table>
             <tr>
               <th>Convention</th>
  @@ -20,17 +20,75 @@
               <th>Enforced By</th>
             </tr>
             <tr>
  +            <td>Every Java source file starts with the Apache licence header.</td>
  +            <td>Required by Apache.</td>
  +            <td>checkstyle</td>
  +          </tr>
  +          <tr>
               <td>No tabs in content</td>
               <td>Programmers should not have to adjust the tab settings in their 
editor to be able to read the source code.</td>
               <td>checkstyle</td>
             </tr>
             <tr>
  -            <th>Indentation of 4 spaces per level</th>
  -            <th>Maximize readability.</th>
  -            <th>Not enforced</th>
  +            <td>Indentation of 4 spaces per level</td>
  +            <td>Maximize readability.</td>
  +            <td>Not enforced</td>
  +          </tr>
  +          <tr>
  +            <td>Comments must be in English</td>
  +            <td>To avoid the need for everyone to learn all languages, English has 
become the standard language for many technology projects, and is the only human 
language that all FOP developers are expected to know.</td>
  +            <td>Not enforced</td>
  +          </tr>
  +          <tr>
  +            <td>Fully qualify all import statements (no "import java.util.*")</td>
  +            <td>Clarity</td>
  +            <td>checkstyle</td>
  +          </tr>
  +          <tr>
  +            <td>No underscores in variable names except for static finals.</td>
  +            <td>Upper/lower case distinctions can be made in all other variable 
names, eliminating the need for artificial word boundaries.</td>
  +            <td>checkstyle</td>
  +          </tr>
  +          <tr>
  +            <td>Opening brace for a block should be on the same line as its control 
statement (if, while, etc.).</td>
  +            <td>Standardization, general preference.</td>
  +            <td>checkstyle</td>
             </tr>
           </table>
           <p>For developers that dislike these conventions, one workaround is to 
develop using their own style, then use a formatting tool like <link 
href="http://astyle.sourceforge.net/";>astyle</link> (Artistic Style) before 
committing.</p>
  +      </section>
  +      <section id="java-checkstyle">
  +        <title>Checkstyle</title>
  +        <p>The java syntax checker "<jump 
href="http://checkstyle.sourceforge.net";>Checkstyle</jump>" is used to enforce many of 
the FOP coding standards.
  +The standards enforced through Checkstyle are documented in its configuration file 
(xml-fop/checkstyle.cfg).
  +The conventions defined in the configuration file are an integral part of FOP's 
coding conventions, and should not be changed without common consent.
  +In other words, the configuration file contains additional conventions that are not 
documented on this page, but are generally accepted as good style within the java 
community (i.e. they are the default behavior of checkstyle, which the FOP developers 
have decided to adopt <em>de facto</em>).
  +Any apparent contradiction between the configuration file and this document should 
be raised on the fop-dev mailing list so that it can be clarified.</p>
  +        <p>To use the "checkstyle" target in FOP's build process, download the 
source from the <jump href="http://checkstyle.sourceforge.net";>Checkstyle web 
site</jump>, place checkstyle-all-*.jar in the lib directory and call "build 
checkstyle". Output (in the build directory) includes checkstyle_report.txt and 
checkstyle_report.xml. If you copy the file contrib/checkstyle-noframes.xsl from 
Checkstyle into FOP's root directory, you will also get an HTML report.</p>
  +        <p>Checkstyle is probably most useful when integrated into your IDE. See 
the Checkstyle web site for more information about IDE plugins.</p>
  +      </section>
  +      <section id="java-best-practices">
  +        <title>Java Best Practices</title>
  +        <p>The following general principles are a distillation of best practice 
expectations on the FOP project.</p>
  +        <ul>
  +          <li>Apply common sense when coding. When coding keep in mind that others 
will read your code and have to understand it.</li>
  +          <li>Readability comes before performance, at least initially.</li>
  +          <li>If you can refactor some code to make it more understandable, please 
do so.</li>
  +          <li>Properly document code, especially where it's important.</li>
  +          <li>Use interfaces instead of implementations where possible.
  +This favors a clearer design and makes switching between implementations easier 
(Examples: List instead of ArrayList/Vector, Map instead of HashMap/Hashtable).</li>
  +
  +
  +          <li>Avoid using exceptions for flow control.</li>
  +          <li>Try to catch exceptions as much as possible and rethrow higher level 
exceptions (meaning hiding the low level detailed and putting a message that is more 
related to the function of your code).</li> 
  +          <li>It is important not to lose the stack trace which contains important 
information.
  +Use chained exception for that. Avalon Framework provides [CascadingException] (and 
similar) for this.
  +Exception class names and stack traces must be treated like gold.
  +Do whatever is required so that this information is not lost.
  +Printing error messages to System.err or System.out is useless in a server-side 
environment where this info is usually lost.</li>
  +          <li>Always log the exception at the higher level (i.e. where it is 
handled and not rethrown).</li> 
  +          <li>Try to avoid catching Throwable or Exception and catch specific 
exceptions instead.</li>
  +        </ul>
         </section>
       </section>
     </body>
  
  
  

---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]

Reply via email to