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]
