...

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.

Analysis and Requirements

Requirements for this release will generally be very dynamic due to multiple customer (university) needs. The requirements should be clearly documented, however readers should accept that they may change throughout the life of the release cycle. Analysis may not be so public but actionable requirements will be drafted and maintained in this Confluence space.

Development

CAS development has been managed using the Apache Maven product. Maven can be used to create Eclipse project files to complement the SVN checkout. We recommend that the Eclipse IDE is used during this development cycle. If Eclipse can be approved by the CAS Steering Committee, it would provide a common IDE and allow the use of new file templates. This would do an excellent job of maintaining a quality source format and consistency.

...

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.

...