Here are some notes about coding style that we should probably try to adhere to to achieve a predictable and uniform look. They are mostly (all?) standard Java style but if there are any disagreements we can sort them out now and vote on them. This first attempt is off the top of my head so please edit if they deviate from any standard. Documentation
One of the (well, my) motivation of going from Beast 1 to Beast II is that lack of documentation in Beast 1 now hampers progress. The good new is that little (less?) code documentation is necessary, since there are various facilities to help code documentation in Beast II:
- Plug-ins should be annotated by the @Description annotation at the top of a class.
- Input-constructors have a tipText argument that should describe the function of an Input.
- Plug-ins can be annotated by the @Citation annotation, if appropriate.
These facilitates a.o. commenting the code, XML-documentation and GUI help information.
- Package Names are all small letters. This means word boundaries may be difficult and packages should attempt to be single word names if possible (and probably no more than 2). Example: beast.mypackage
- Class Names are inter-capitalated and start with a capital. Example: MyJavaClass?.
- Class Names are unique under a same path in the entire name space including BEAST 2 core, all depended packages and 3rd party libraries. A duplicated class name has to be created in a different path. For example, beast.math.util.MathUtils and org.apache.commons.math.util.MathUtils are fine, but you cannot create a class MathUtils again under the path beast.math.util in any other packages.
- Class members are inter-capitalated but start with a small letter. Example: myInstance
- Static final constants are all capitals with underscores to delimit words. Example: MY_CONSTANT
- As IDEs colour member variables/statics etc., we don’t need to use codes/prefixes to denote these (or types). Yeah right…
- Use a full descriptive name (i.e., no contractions – these can be hard to predict and search for).
- No acronyms in public names unless really well-known and ubiquitous (i.e., MCMC).
- Acronyms that start a name that would normally start with a small lettter (class member) the whole acronym should be small letters (i.e., mcmcOptions).
3rd Party Libraries
- The same library (./lib/*.jar) will only be loaded once across all packagas. For example: commons-math3-3.1.1.jar is part of BEAST 2 core, so that the package developer cannot load it again in any other packages. Since jar files will only be dynamically loaded by BEAST at start-up and these jars are checked for duplicate classes, including a different version of commons-math*.jar in a package means it may not be loaded. Requests of upgrading 3rd party libraries can send to BEAST 2 development team.