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:
- You are not allowed to write any production code unless it is to make a failing unit test pass.
- You are not allowed to write any more of a unit test than is sufficient to fail; and compilation failures are failures.
- 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.
| Initial | Stands for | Concept |
|---|---|---|
| S | SRP | Single responsibility principle. A class should have only a single responsibility (i.e. only one potential change in the software's specification should be able to affect the specification of the class) |
| O | OCP | Open/closed principle “software entities … should be open for extension, but closed for modification.” |
| L | LSP | Liskov substitution principle “objects in a program should be replaceable with instances of their subtypes without altering the correctness of that program.” |
| I | ISP | Interface segregation principle “many client-specific interfaces are better than one general-purpose interface.” |
| D | DIP | Dependency inversion principle one should “Depend upon Abstractions. Do not depend upon concretions.” |
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:
| REP | The Release Reuse Equivalency Principle | The granule of reuse is the granule of release. |
| CCP | The Common Closure Principle | Classes that change together are packaged together. |
| CRP | The Common Reuse Principle | Classes that are used together are packaged together. |
The last three principles are about the couplings between packages, and talk about metrics that evaluate the package structure of a system.
| ADP | The Acyclic Dependencies Principle | The dependency graph of packages must have no cycles. |
| SDP | The Stable Dependencies Principle | Depend in the direction of stability. |
| SAP | The Stable Abstractions Principle | Abstractness increases with stability. |