Introduction

Analysis and Requirements

Development

...

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.)

files
The java compiler enforces the convention that file names have the same base name as the public class they define.

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.

• When it makes sense, consider writing a main for any complex classes that would benefit from an example use case. This should not be the norm. Unit tests should be written for all classes. This would be for the casual source code browser's understanding.

• We do not recommend the use of multiple classes in a single Java file. The only exception to this would be something very natural such as a Comparator.

• Declare a class as final only if it is a subclass or implementation of a class or interface declaring all of its non-implementation-specific methods. (And similarly for final methods). Making a class final means that no one ever has a chance to reimplement functionality. Defining it instead to be a subclass of a base that is not final means that someone at least gets a chance to subclass the base with an alternate implementation. Which will essentially always happen in the long run.

• Never declare instance variables as public.

• Minimize statics (except for static final constants). Static variables act like globals in non-OO languages. They make methods more context-dependent, hide possible side-effects, sometimes present synchronized access problems. and are the source of fragile, non-extensible constructions. Also, neither static variables nor methods can be overridden in any useful sense in subclasses.

• We generally prefer Long over long, long over int, and double over floats. But use int for compatibility with standard Java constructs and classes (for the major example, array indexing, and all of the things this implies, for example about maximum sizes of arrays, etc). Arithmetic overflow and underflow can be 4 billion times less likely with longs than ints; similarly, fewer precision problems occur with doubles than floats. On the other hand, because of limitations in Java atomicity guarantees, use of longs and doubles must be synchronized in cases where use of ints and floats sometimes would not be.

• 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 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.

• Avoid giving a variable the same name as one in a superclass. This is usually an error. If not, explain the intent.

• Use Java 1.5 features and type-safety

• Name methods with logical action verbs

• Always set returns to false if that what's expected. Return the local variable and not the result.

• Do not return "this".

• Declare all public methods as synchronized; or if not, describe the assumed invocation context and/or rationale for lack of synchronization. In the absence of planning out a set of concurrency control policies, declaring methods as synchronized at least guarantees safety (although not necessarily liveness) in concurrent contexts (every Java program is concurrent to at least some minimal extent). With full synchronization of all methods, the methods may lock up, but the object can never enter in randomly inconsistent states (and thus engage in stupidly or even dangerously wrong behaviors) due to concurrency conflicts. If you are worried about efficiency problems due to synchronization, learn enough about concurrent OO programming to plan out more efficient and/or less deadlock-prone policies.

These recommendations are rules of thumb and may not be followed in all cases. They are here for guidance only.

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.

Delivery