vmote 2003/10/16 09:50:13
Modified: src/documentation/content/xdocs/dev conventions.xml
Log:
update code conventions from resolved issues on the FOPDevelopersStyleGuide wiki
Revision Changes Path
1.6 +20 -5 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.5
retrieving revision 1.6
diff -u -r1.5 -r1.6
--- conventions.xml 15 Sep 2003 20:54:03 -0000 1.5
+++ conventions.xml 16 Oct 2003 16:50:13 -0000 1.6
@@ -20,7 +20,7 @@
<title>Java</title>
<section id="java-style">
<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.
+ <p>In order to facilitate the human reading of FOP source code, reduce
churning in code, and prevent disputes, 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, the FOP developers have agreed to other conventions, which are
summarized in the following table:</p>
<table>
@@ -35,21 +35,28 @@
<td>checkstyle</td>
</tr>
<tr>
- <td>No tabs in content</td>
+ <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>
- <td>Indentation of 4 spaces per level</td>
+ <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>Comments, identifiers, and project documentation must be in English.
+In general, other languages must not be used, except in translated documentation
and language-specific i10n files.
+ </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>American English spelling should be used. Alternative spelling and
idioms are tolerated, but may be changed by anyone to American.</td>
+ <td>Some standard is useful, and American English is widely used and
accepted for technology standards and projects.</td>
+ <td>Not enforced.</td>
+ </tr>
+ <tr>
<td>Fully qualify all import statements (no "import java.util.*")</td>
<td>Clarity</td>
<td>checkstyle</td>
@@ -68,6 +75,14 @@
<td>Write appropriate javadoc entries for all public and protected
classes, methods, and variables.</td>
<td>Basic API documentation is needed.</td>
<td>checkstyle</td>
+ </tr>
+ <tr>
+ <td>Personal attribution in the source code, such as @author tags and
attribution comments should not be used.
+Excepted from this general rule are potentially confusing or wide-ranging changes.
+If such changes prove useful over time, the related comments should be removed.</td>
+ <td>Personal attribution tends to clutter the code.
+The relevant historical information that might be useful for problem-solving is
tracked in the code repository.</td>
+ <td>Not enforced. Anyone is free to remove such comments.</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>
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
