OpenSpecimen Suite is the next-generation tissue banking application which integrates the functionality of the existing caBIG™ TBPT (Tissue bank and pathology Tools). The tool will make it easier for researchers to locate and analyze tissue specimens for use in cancer research that is based on tissue, clinical, and genomic characteristics.Licensing
All OpenSpecimen source and pre-built binaries are provided under the <OpenSpecimen Open Source License>
The OpenSpecimen community exists primarily through discussion groups/forums, the <issue tracker> and, to a lesser extent, the source control repository. You are encouraged to contribute to the discussion and you can also help us to keep the effectiveness of the groups high by following and promoting the guidelines listed here.
Showing courtesy and respect to others is a vital part of the OpenSpecimen culture, and we strongly encourage everyone participating in OpenSpecimen development to join us in accepting nothing less. There's never a reason to be antagonistic or dismissive toward anyone who is sincerely trying to contribute to a discussion.
Refer to the discussion groups/forums. Specifically the OpenSpecimen development forum.
See <issue tracker> for details on how issues are reported and tracked for OpenSpecimen.
If you want to get your hands dirty with the code inside OpenSpecimen, the <Community Code Contribution> is the right place to start.
Testing is very important to maintaining the quality of OpenSpecimen. Unit Tests must be written for any new code, and changes must be verified to not break existing tests before they are submitted for code review. Please see sections below for a more detailed description of OpenSpecimen Testing approach.
Please see the conventions described below.
You may use any IDE (or even a simple text editor) to do OpenSpecimen development. Please refer to the <Community Code Contribution> document for details about setting up the Eclipse environment.
The OpenSpecimen Technical Administration Guide describe the OpenSpecimen architecture. The guide focuses on administrative tasks associated with the use of OpenSpecimen Suite and mainly focuses on using the application program interface in the OpenSpecimen Suite application for data entry and query operations. New developers should read over the guide first to make sure they understand the big picture of OpenSpecimen development.
As OpenSpecimen is open source, we're excited that to make it possible for our users to fix bugs and create new features, and we hope to get great patches from the community. Before you fire up your favorite IDE and begin hammering away at that new feature, though, please take the time to read this section and understand the process. While it seems rigorous, we want to keep a high standard of quality in the code base. Also, please be aware that the code contributors must sign a Contributor License Agreement before we can accept any code.
To keep the source consistent, readable, diffable and easy to merge, we use a fairly rigid coding style, and all patches will be expected to conform to the style outlined here. To keep things as simple as possible, many of these style rules will be automatically verified by the caTissue build; style issues that can't be caught by the build system must be addressed during code review.
Most of the conventions are described with the PMD and Checkstyle rulesets, as mentioned in the sections above, and are enforced by the build. As there are exceptions to every rule, you can override these PMD and Checkstyle rules with appropriate annotations in the code. If you do, be sure to document the reason in an adjacent comment.
We describe some of the key conventions explicitly below.
Every file must have a license header at the top, prefaced with a copyright notice. A package statement and import statements should follow, each block separated by a blank line. Next is the class or interface declaration. In the Javadoc comments, describe what the class or interface does. Include an _@author_ tag.
Each public method or constant must likewise have Javadoc describing what it does. For methods, this must include documenting the arguments, return values, and possible exceptions. Expectations of parameters, such as whether they can be null, should be documented. The javadoc should describe behavior for all combinations of inputs, paying particular attention to edge cases.
Within method bodies, comments should be used as needed to document blocks of code that are doing something tricky or complex. In general, strive for self-documenting code.
Every file should have a and copyright notice. A package statement and import statements should follow, each block separated by a blank line, followed by the class or interface declaration. Both the class and each public method or field must have Javadoc documenting it.
You should endeavor to keep classes and methods to a reasonable size, both in terms of total lines of code and of cyclomatic complexity (number of nested loops and conditionals). Methods should generally fit on a screen without having to scroll. When classes and methods begin to grow beyond this size, look to factor out helper classes and methods to keep their size acceptable.
"Star" imports are prohibited, as they make it difficult to determine where classes come from in a large codebase.
Static imports should be used sparingly and only for very common DSL-style operations whose provenance will generally be well-known. Some examples include JUnit _assert_ methods and Mockito methods in unit tests.
The order within a Java file be:
Treat acronyms and abbreviations as words. The names are much more readable. This applies in the case where the acronym is the entire word as well.
Good | Bad |
---|---|
XmlHttpRequest | XMLHTTPRequest |
getCustomerId | getCustomerID |
class Html | class HTML |
Parameterized type names should be one capital letter. The exception is when there are multiple parameter types, and a short 2-3 letter name (e.g. ID) is more descriptive.
Good | Bad |
---|---|
Foo<T> | Foo<FooClientType> |
Bar<K, V> | Bar<KeyType, ValueType> |
Dao<ID, T> | Dao<ID, SERIALIZABLE> |
The project includes Eclipse formatter rules that describe the caTissue formatting conventions. If you import the project into Eclipse, as described earlier, Eclipse will automatically be configured to enforce the formatting when you either manually format or save the file.
Below we describe explicitly some of the key formatting rules.
We use 4-space indentation. The indentation should be done using spaces, not tabs - most IDEs have configuration options to ensure this.
Each line of text in your code should be at most 120 characters long. Use linefeed characters to break lines (Unix-style).
Any code block (for / while / if / etc) must be enclosed in curly braces, even if it is only a single line. The opening braces should be on the same line as the if / for / while.if (condition) {
doX();
doY();
{color:#000000}}
This example class illustrates the conventions and formatting rules described above./*
*caTissue LICENSE header \*/ package gov.nci.nih.catissue; import java.util.List; import java.util.LinkedList; import org.apache.commons.lang.StringUtils; import gov.nih.nci.catissue.util.Utils; /*\* * Custom implementation of Stack specifically for integers, for enhanced performance.} \* * @author dkokotov \*/ public class MyIntStack { private final LinkedList fStack; public MyIntStack() { fStack = new LinkedList(); } public int pop() { return ((Integer) fStack.removeFirst()).intValue(); } public void push(int elem) { fStack.addFirst(new Integer(elem)); } public boolean isEmpty() { return fStack.isEmpty(); } |
Tests are very important, and we require submissions that include them, adding new tests for new functionality or updating existing tests for bug fixes.
Tests for Java classes must be placed in a parallel source tree under test and the test class name must be suffixed with Test. For example:src/main/java/gov/nih/nci/catissue/Utils.java
src/test/java/gov/nih/nci/catissue/Utils.java
The use of the parallel test tree has two major advantages:
There are a few different kinds of tests in caTissue
If you have developed a new feature or a bug fix for caTissue, we welcome your contribution. This section describes the steps you should take to submit your contribution. There are three paths a contribution may take:
Options B and C exist for cases where the contribution does not fit the near-term goals of the project, and enables that contribution to still have a path to be made available to interested members of the community.
The first steps of the contribution process are common to all three options; after that, the paths for the contribution diverge.
Where warranted, we encourage you to continue working on the code in collaboration with the caTissue development team and continue to support the code.
The current members of the caTissue development team are the only committers at present. However, contributors can become committers by demonstrating a track record of high-quality submissions and community participation, as well as a sufficient time commitment to the project.
Before we can accept a patch from you, you must sign a Contributor License Agreement (CLA). The CLA protects you and us.