| <?xml version="1.0"?> |
| <!-- |
| Licensed to the Apache Software Foundation (ASF) under one |
| or more contributor license agreements. See the NOTICE file |
| distributed with this work for additional information |
| regarding copyright ownership. The ASF licenses this file |
| to you under the Apache License, Version 2.0 (the |
| "License"); you may not use this file except in compliance |
| with the License. You may obtain a copy of the License at |
| |
| http://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, |
| software distributed under the License is distributed on an |
| "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| KIND, either express or implied. See the License for the |
| specific language governing permissions and limitations |
| under the License. |
| --> |
| |
| <document> |
| |
| <properties> |
| <title>Coding Standards</title> |
| </properties> |
| |
| <body> |
| |
| <section name="Coding Standards"> |
| |
| <p> |
| This document describes a list of coding conventions that are required |
| for code submissions to the project. By default, the coding conventions |
| for most Open Source Projects should follow the existing coding conventions |
| in the code that you are working on. For example, if the bracket is on |
| the same line as the if statement, then you should write all your code |
| to have that convention. |
| </p> |
| |
| <p> |
| <strong>If you commit code that does not follow these conventions, you |
| are responsible for also fixing your own code.</strong> |
| </p> |
| |
| <p> |
| Below is a list of coding conventions that are specific to Turbine, |
| everything else not specificially mentioned here should follow the official |
| <a href="http://java.sun.com/docs/codeconv/html/CodeConvTOC.doc.html">Sun |
| Java Coding Conventions</a>. |
| </p> |
| |
| <p> |
| 1. Brackets should begin and end on a new line and should exist even |
| for one line statements. Examples: |
| </p> |
| |
| <source test=""><![CDATA[ |
| if (foo) |
| { |
| // code here |
| } |
| |
| try |
| { |
| // code here |
| } |
| catch (Exception bar) |
| { |
| // code here |
| } |
| finally |
| { |
| // code here |
| } |
| |
| while (someCondition) |
| { |
| // code here |
| } |
| ]]></source> |
| |
| <p> |
| 2. Though it's considered okay to include spaces inside parens, the |
| preference is to not include them. Both of the following are okay: |
| </p> |
| |
| <source test=""><![CDATA[ |
| if (foo) |
| |
| or |
| |
| if ( foo ) |
| ]]></source> |
| |
| <p> |
| 3. 4 space indent. <strong>NO tabs</strong>. Period. We understand |
| that many developers like to use tabs, but the fact of the matter is |
| that in a distributed development environment where diffs are sent to |
| the mailing lists by both developers and the version control system |
| (which sends commit log messages), the use tabs makes it impossible to |
| preserve legibility. |
| </p> |
| |
| <p> |
| In Emacs-speak, this translates to the following command: |
| </p> |
| |
| <source><![CDATA[ |
| (setq-default tab-width 4 indent-tabs-mode nil) |
| ]]></source> |
| |
| <p> |
| 4. Unix linefeeds for all .java source code files. Other platform specific |
| files should have the platform specific linefeeds. |
| </p> |
| |
| <p> |
| 5. JavaDoc <strong>MUST</strong> exist on all methods. If your code |
| modifications use an existing class/method/variable which lacks |
| JavaDoc, it is required that you add it. This will improve the |
| project as a whole. For guidelines on how to write proper |
| JavaDocs, see |
| <a href="http://java.sun.com/j2se/javadoc/writingdoccomments/index.html"> |
| Sun's guidelines</a> |
| </p> |
| |
| <p> |
| 6. When writing javadocs for variables, try to keep the comment on just |
| one line. |
| </p> |
| <source><![CDATA[ |
| /** Documentation of this variable */ |
| private int myVariable; |
| |
| /** |
| * If the documentation of the variable is enough to occupy multiple |
| * lines, then this form of comment is also perfectly acceptable. |
| */ |
| private int myVariable; |
| ]]></source> |
| |
| <p> |
| 7. The ASL 2.0 License <strong>MUST</strong> be placed at the top |
| of each and every file. |
| </p> |
| |
| <p> |
| 8. If you contribute to a file (code or documentation), add yourself to the |
| authors list at the top of the file. You should add yourself to the end of |
| the list of authors. For java files the preferred Javadoc format is: |
| </p> |
| |
| <source><![CDATA[ |
| @author <a href="mailto:user@domain.com">John Doe</a> |
| ]]></source> |
| |
| <p> |
| 9. All .java files should have a @version tag like the one below. |
| </p> |
| |
| <source><![CDATA[ |
| @version $Id$ |
| ]]></source> |
| |
| <p> |
| 10. Import statements must be fully qualified for clarity. |
| </p> |
| |
| <source><![CDATA[ |
| import java.util.ArrayList; |
| import java.util.Hashtable; |
| |
| import org.apache.foo.Bar; |
| import org.apache.bar.Foo; |
| ]]></source> |
| |
| <p> |
| And not |
| </p> |
| |
| <source><![CDATA[ |
| import java.util.*; |
| import org.apache.foo.*; |
| import org.apache.bar.*; |
| ]]></source> |
| |
| <p> |
| 11. Import statements should be listed in alphabetical order. Use blank lines |
| to separate products. In cases where there is a large number of imports from a |
| single product (like java.x) consider separating at the second level. For example, |
| you could group all of the java.util, java.swing, etc... |
| </p> |
| |
| <p> |
| 12. The conditional part of if and while statements should not use |
| the equality operator for testing true or false values. |
| </p> |
| |
| <source test=""><![CDATA[ |
| if (foo) |
| |
| and not |
| |
| if (foo==true) |
| ]]></source> |
| |
| <p> |
| 13. Always use the short form of the classname in code. Certain exception |
| do apply where the fully qualified classname is required such as when |
| java.sql.Date and java.util.Date are used in the same class. Otherwise, you |
| should always import the class and use the short name. |
| </p> |
| |
| <source test=""><![CDATA[ |
| try |
| { |
| } |
| catch (IOException e) |
| { |
| } |
| |
| and not |
| |
| try |
| { |
| } |
| catch (java.io.IOException e) |
| { |
| } |
| ]]></source> |
| |
| <p> |
| 14. Avoid using Iterators that are initialized outside of the loop. |
| </p> |
| |
| <source test=""><![CDATA[ |
| for (Iterator iter=getIterator(); iter.hasNext; ) |
| { |
| } |
| |
| and not |
| |
| Iterator iter=getIterator(); |
| for (;iter.hasNext; ) |
| { |
| } |
| ]]></source> |
| |
| <hr noshade="true" size="1"/> |
| |
| <p> |
| X/Emacs users might appreciate this in their .emacs file. |
| </p> |
| |
| <source><![CDATA[ |
| (defun apache-turbine-mode () |
| "The Java mode specialization for Apache Turbine projects." |
| (if (not (assoc "apache-turbine" c-style-alist)) |
| ;; Define the Apache Turbine cc-mode style. |
| (c-add-style "apache-turbine" '("java" (indent-tabs-mode . nil)))) |
| |
| (c-set-style "apache-turbine") |
| (c-set-offset 'substatement-open 0 nil) |
| (setq mode-name "Apache Turbine") |
| |
| ;; Turn on syntax highlighting when X is running. |
| (if (boundp 'window-system) |
| (progn (setq font-lock-support-mode 'lazy-lock-mode) |
| (font-lock-mode t)))) |
| |
| ;; Activate Turbine mode. |
| (if (fboundp 'jde-mode) |
| (add-hook 'jde-mode-hook 'apache-turbine-mode) |
| (add-hook 'java-mode-hook 'apache-turbine-mode)) |
| ]]></source> |
| |
| <p> |
| Thanks for your cooperation. |
| </p> |
| |
| |
| </section> |
| |
| </body> |
| </document> |