A good developer knows that there is more to development than programming. A great developer knows that there is more to development than development. | |
| (Ambler, 1999) |
The purpose of this document is to establish a set of standards for any code written in Java for use in WAF.
Why have conventions?
Most of the lifetime cost of a piece of code is maintenance.
Over its lifetime, code is usually maintained by people other than the original author.
Conventions improve the readability of code by providing a consistent level of quality.
Open source code is shipped as one of the pieces of the product. The code must be as clean and well packaged as other pieces of the product.
Code is not written for compilers alone. People read your code, and style matters. For an approach to English, a good starting point is The Elements of Style by Strunk & White [1].
In general, when programming for WAF, follow the Sun Java, JSP, and Javadoc conventions:
Code Conventions for the Java Programming Language — http://java.sun.com/docs/codeconv/html/CodeConvTOC.doc.html
Code Conventions for the JavaServer Pages Technology Version 1.x Language — http://developer.java.sun.com/developer/technicalArticles/javaserverpages/code_convention/
Writing Javadoc comments — http://java.sun.com/j2se/javadoc/writingdoccomments/index.html
This chapter discusses WAF coding conventions where they differ from the Sun conventions or if they cover something that is not in the standard convention.
Import statements should be alphabetized, separated into sections of relevant functionality, and enumerated without using *.
All lines of source code should be indented uniformly using spaces and not tabs. Four spaces is the norm, although in some cases more space is required. Two spaces is forbidden under all circumstances.
Class fields, unless constants, are private. A private field called foo is named m_foo. A static private field called foo is named s_foo.
Exceptions are used to signal erroneous behavior or usage inside of a class. All stubbed methods should throw a runtime Error or UnsupportedOperationException with appropriate comments. Do not write generic catch (Exception e) blocks; catch the specific exceptions instead.
Acronyms, such as JDBC or URL, should always be capitalized when used. For instance, write JDBCLoader instead of JdbcLoader. This makes it clear that the letters are part of an acronym and is easier to read because it matches how it is referred to in English prose. Abbreviations that are not acronyms should have their first letter capitalized, with the exception of ID.
When debugging, avoid using System.out.println or System.err.println. Instead, use Log4j as described in Section 8.5 Using logging for debugging.
| [1] |