Introduction
Analysis and Requirements
Development
Coding Standards
The following text was compiled from the experience of the authors, other projects, and intellectual material that has been declared public domain. It is here in dynamic form and pending approval of the CAS Steering Committee.
Introduction
Development guidelines are written here to help CAS developers maintain consistency and quality in the source that we write. The product is Java source code or artifact resources. Stiff process is not required, however guidelines are helpful in the act of quality compliance. Software among team members should reflect no individual authorship. These guidelines will help with this goal.
Development
Standard Tools & Libraries
The CAS project has currently standardized on the following libraries:
- Spring Framework
- Spring Web Flow
- Spring LDAP
- JaValid
- Maven2
The project makes no recommendations about IDEs. Currently, developers use either Eclipse or IntelliJ. IntelliJ has generously provided Open Source Licenses for the CAS Development Team. If you require a license, please contact ScottS
Coding Standards
Setters/Getters vs. Constructors
For Spring Managed Classes: All required properties should be set via Constructor. All optional properties should be set via setters/getters. This makes it easy to distinguish between required and optional properties.
For Non-Spring Managed Classes: These should have the option of setting all properties via constructor, as they may be instantiated inline as instance variables.
Readability
The majority of developers these days have larger, widescreen monitors. To that end, the code should favor longer lines, rather than breaking a line into multiple lines. Thus, method signatures, unless exceptionally long, should appear on one line.
The current recommendation for line length is 140 characters.
Validation
All classes that will be managed by Spring should leverage the JaValid annotations for dependency checking of properties at deployment time.
Formatting
Java coding standards should follow the guidelines set forth by Sun Microsystems. These guidelines are titled Code Conventions for the Java Programming Language and found here. Other clarifications should be noted in addition to those found above.
Naming Conventions
packages
lowercase
Consider using the recommended domain-based conventions described in the Java Language Specification, page 107 as prefixes. (For example, edu.oswego.cs.dl.)
...
classes
CapitalizedWithInternalWordsAlsoCapitalized
Exception class
ClassNameEndsWithException
Interface
Name the entity as it would generally be named:
MyService
Class
When necessary to distinguish from similarly named interfaces:
MyServiceImpl
constants (finals):
UPPER_CASE_WITH_UNDERSCORES
*private or protected:_
firstWordLowerCaseButInternalWordsCapitalized
static private or protected:
firstWordLowerCaseButInternalWordsCapitalized
local variables:
firstWordLowerCaseButInternalWordsCapitalized
methods:
firstWordLowerCaseButInternalWordsCapitalized()
factory method for objects of type X:
newX
converter method that returns objects of type X:
toX
method that reports an attribute x of type X:
X x() or X getX().
method that changes an attribute x of type X:
void x(X value) or void setX(X value).
Recommendations
- Minimize * forms of import. Be precise about what you are importing. Check that all declared imports are actually used. Do not leave imports that are not used. If we use an IDE such as Eclipse it is easy to manage imports.
...
- Use final and/or comment conventions to indicate whether instance variables that never have their values changed after construction are intended to be constant (immutable) for the lifetime of the object (versus those that just so happen not to get assigned in a class, but could in a subclass). Access to immutable instance variables generally does not require any synchronization control, but others generally do.
- We generally prefer protected over private. Unless you have good reason for fixing a particular strategy to use a variable or method, you might as well plan for change via subclassing. On the other hand, this almost always entails more work. Basing other code in a base class around protected variables and methods is harder, since you you have to either loosen or check assumptions about their properties. (Note that in Java, protected methods are also accessible from unrelated classes in the same package. There is hardly ever any reason to exploit this though.)We always believe in getter/setter methods. While we've borrowed much of Doug Lea's guidelines, all instance variables should have a get and set method. It is not important to document these methods. We know what they represent.
...
These recommendations are rules of thumb and may not be followed in all cases. They are here for guidance only.
Formatting and Templates
It is recommended that the development team adopt a template if e.g. Eclipse were used for development. IDE is not too important, but the code that we write should be formatted in the same manner. Tabs should not be allowed. And during code reviews they should be removed if found.
...
Code Reviews
After source files are checked in, periodic code reviews should be done as a group or peer-to-peer as development begins. Depending on the skill level of the team members, group or peer-to-peer should be chosen. Code reviews are necessary and should not be avoided.
Testing
All classes and methods should have corresponding JUnit tests. JavaBeans are exempt. If team members were to pick and choose what is tested, quality will suffer.