Coding Practices

In order to :

• improve the quality of the code
• reduce the noise in the build
• improve the design of the framework
• reduce the learning curve for new developers

we have adopted the following practices in re-factoring the framework.

No Warnings

Code should not be submitted for acceptance into the trunk with warnings unless there is a good reason

• dependency on deprecated code that can not be fixed without a functional change that is unacceptable.
  
  

Java provides these for a reason. 

No missing or incomplete JavaDocs

JavaDocs help in three major ways.

• They force the person writing them to think about the design and come up with a clear explanation of what the class or method is supposed to do.
• They allow a reviewer to more easily understand the reason for the class or method so it can be assessed for complexity, level and need.
• They give a person who needs to use the method an easy way to understand the functionality and use case that the class or method addresses

These are particularly important during a re-factoring when a lot of changes are being done quickly and everyone needs to be on the same page to avoid big problems.

Test-driven development

The Three Laws of TDD. 

Test Driven Development is described in this article in terms of three simple rules. They are:

1. You are not allowed to write any production code unless it is to make a failing unit test pass.
2. You are not allowed to write any more of a unit test than is sufficient to fail; and compilation failures are failures.
3. You are not allowed to write any more production code than is sufficient to pass the one failing unit test.

The article describes the benefits and application of these three rules.

It takes a lot of discipline but the rewards in productivity and code robustness are worth it.

Apply SOLID design principles

SOLID (Single responsibility, Open-closed, Liskov substitution, Interface segregation and Dependency inversion) is a mnemonic acronym that stands for five basic principles of object-oriented programming and design. The principles, when applied together, intend to make it more likely that a programmer will create a system that is easy to maintain and extend over time.

The principles of SOLID are guidelines that can be applied while working on software to remove code smells by causing the programmer to refactor the software's source code until it is both legible and extensible. It is part of an overall strategy of agile and Adaptive Software Development.

When updating or re-factoring code or when designing new modules, please test your design against these principles.

For more information and generally good reading about design try PrinciplesOfOod and SOLID Principles.

Packaging

One of the goals of this re-factoring project is to restructure the packaging. The following principles will guide this effort.

The first three package principles are about package cohesion, they tell us what to put inside packages:

The last three principles are about the couplings between packages, and talk about metrics that evaluate the package structure of a system.