update code conventions from resolved issues on the FOPDevelopersStyleGuide wiki

git-svn-id: https://svn.apache.org/repos/asf/xmlgraphics/fop/trunk@196963 13f79535-47bb-0310-9956-ffa450edef68

1 files changed, 19 insertions, 4 deletions

diff --git a/src/documentation/content/xdocs/dev/conventions.xml b/src/documentation/content/xdocs/dev/conventions.xml
index 12063b953..d6bfb5362 100644
--- a/src/documentation/content/xdocs/dev/conventions.xml
+++ b/src/documentation/content/xdocs/dev/conventions.xml
@@ -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 @@ In addition, the FOP developers have agreed to other conventions, which are summ
             <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>
@@ -69,6 +76,14 @@ In addition, the FOP developers have agreed to other conventions, which are summ
             <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>
       </section>