Rather than only including cosmetic items like formatting and naming rules (although we do have formatting guidelines and templates), the initial version of the CONNECT coding standards will focus more on principles - the attributes of our software and the processes that are followed that result in a good product.
As a project new to the open source community, we are finding our way to the balance between making it easy to contribute ("send me whatever you have, and we the stewards will integrate!") and making it easy to integrate ("I am only going to accept code that looks exactly perfect!"). If the guidelines are too tight, no one will want to contribute; if the guidelines are too loose, there will be great overhead in the stewards refactoring code for inclusion in the baseline.
One way to look at these guidelines are these are the standards for those committing code to the baseline.
The project values all contributions! The closer the submissions are to the guidelines, the sooner they will be able to be adopted into the baseline.
These guidelines belong to the community. Please provide feedback
Core Development Principles
This section list those principles that are of the highest value to the project.
Checked-in code MUST compile
Code that is checked into a non-private area of source control that does not compile is bad. Code should compile both from command line and from your IDE.
Favor self-documenting code over comments
Comments to explain implementation tend to become stale over time. Instead, rely on descriptive method and variable names to make the code easy to read. Reserve implementation comments for explaining difficult concepts.
Favor loosely coupled components
CONNECT components are to be loosely coupled by using writing to interfaces. Following the "component proxy pattern" (insert link) provides for loose coupling.
Test early, test continuously
Rather than waiting until a large feature set is completely developed prior to including in the baseline, strive to get a sliver of functionality developed, checked-in, and deployed early. This allows for early testing in an independent test environment. The earlier the code is submitted, the more time react to deployment and integration issues.
Favor frequent, small check-ins
Checked-in code should be covered by automated tests
In order to ensure that code meets its purpose, and to prevent regression when making modifications, code should be accompanied by a mix of unit and integration tests.
- Automated Testing Coding Guidelines
- Commit Messages
- Database Access
- Development Environment
- Directory Structure
- General OO Principles
- Java Naming Conventions and Formatting
- Check for NPE in factory methods
- Code Control Ignore List
- Coding templates and formatters
- Component Proxy Model Guidelines
- Naming Conventions
- NhinTargetCommunitiesType vs. NhinTargetSystemType