Development Conventions

Efficient team work that produces high-quality software requires a common set of rules.

Consistent Source Tree

Update your sources and run the build locally before every check-in. Commit only if the build succeeds.

Documentation is part of the product. Whenever you implement a new feature or change existing behavior make sure to update all corresponding JavaDoc as well as other documentation with the same change set. The product should always be in a consistent state. For every change the following items should be checked:

• Corresponding JavaDoc.
• Documentation referring to the modified concepts, interfaces or implementation.
• New features, bug fixes and modified behavior should be enlisted in the org.jacoco.doc/docroot/doc/changes.html file together with the corresponding issue tracker id.

Design for Integration

The primary focus of the JaCoCo project is to provide a code coverage library. Integrators may want to embed JaCoCo in different tools and environments with very different usage scenarios. Therefore following aspects should be considered:

Documentation: All APIs should be properly documented on different levels of granularity:

• General usage
• Bundle summary
• Package summary
• Type description
• Member description

Proper Units: All APIs and internal implementation classes should form proper units with well defined responsibilities and dependencies. Each class and method should focus on a single concept. It should be possible to use different aspects separately.

Abstraction: All APIs must use the most general abstractions possible. For instance reading binary data should rely on the java.io.InputStream interface, not on a java.io.File object.

System Dependencies: Avoid any dependencies to the local file system, network resources, threads, processes etc.

Test Driven Development

All code added to JaCoCo should have corresponding JUnit test cases. Ideally tests are developed before or along with the actual implementation:

• Every new feature should be verified by test cases.
• Modified behavior should also be reflected by test cases.
• Ideally for every reported bug a reproducer is added to the unit tests.

Keep an Eye on License Issues

All code included with JaCoCo must conform to the EPL license.

• Every committer and contributor must agree that all code will be published under EPL. He or she must be the original author and must have the permission to contribute code to JaCoCo, for example if such a permission is required by the employer.
• Every third party content must be enlisted in the corresponding about.html file along with its license.
• Every third party content included with the JaCoCo distribution must be enlisted in the org.jacoco.doc/docroot/doc/license.html file and the corresponding about.html file along with its license.
• Every source file (Java, Build Script, DTD) must have a EPL license notice. The initial contributor should be listed. In case of significant changes or additions additional contributors should also be listed.