This is the Metrics Team Java Style Guide, which not only is concerned with coding style but which also contains recommendations for setting up Java projects in Metrics.
== Dependencies ==
## Dependencies
Ideally the Java JDK alone should do. If that is not sufficient, mature libraries available in current Debian stable are fine.
A 'mature' library is a well tested and widely used library, e.g. Apache commons-lang or logback. In addition, we follow these [wiki:org/operations/Guidelines guidelines].
A 'mature' library is a well tested and widely used library, e.g. Apache commons-lang or logback. In addition, we follow these [guidelines](./org/operations/Guidelines).
Additional dependencies that are not part of the release and not necessary for preparing a release are less restricted. For example, for coding style conformance we use checkstyle version > 6, which is not part of Debian stable, as the Debian stable version cannot support the functionality needed here.
== Build Environment ==
## Build Environment
Metrics Java projects use Ant as opposed to Maven or similar tools.
Ant gives us tighter control over dependencies and is very flexible to serve all development needs.
Metrics' java projects also should make use of [https://gitweb.torproject.org/metrics-base.git metrics-base] in order to avoid multiplying ant task implementations (see [https://gitweb.torproject.org/collector.git/tree CollecTor's git repository] for a usage example).
Metrics' java projects also should make use of [metrics-base](https://gitweb.torproject.org/metrics-base.git) in order to avoid multiplying ant task implementations (see [CollecTor's git repository](https://gitweb.torproject.org/collector.git/tree) for a usage example).
=== Unit Testing ===
### Unit Testing
Currently, testing is facilitated by JUnit.
Not every project has a test coverage of 90% or more (yet).
In order to achieve this goal, patches should aim at 100% test coverage.
== Code Metrics ==
## Code Metrics
In order to provide high quality code we use various code metrics.
In the future, we will consider to add other metrics to this list.
Ticket #19731 discusses these topics in detail.
=== Coverage and Complexity ===
### Coverage and Complexity
Test coverage is measured by Cobertura. The Cobertura results also contain code complexity metrics.
We currently have a higher priority for test coverage, but eventually we will also take code complexity into account for improvement.
The cobertura check is always set (and should be adapted) to ensure that coverage doesn't decrease.
=== Conformance to the Style Guide ===
### Conformance to the Style Guide
The coding style is checked by checkstyle. Currently, not all projects confirm to the style guide (completely).
That's why patches should not introduce new checkstyle complaints.
== File Structure of Java Projects ==
## File Structure of Java Projects
This is the common file structure for Metrics Team's java projects.
It is adapted from [https://maven.apache.org/guides/introduction/introduction-to-the-standard-directory-layout.html Maven's standard structure]:
It is adapted from [Maven's standard structure](https://maven.apache.org/guides/introduction/introduction-to-the-standard-directory-layout.html):
{{{
#!html
```
<table border="1" class="table table-striped">
<tr>
<td align="left"><tt>src/main/java</tt></td>
...
...
@@ -78,15 +77,15 @@ It is adapted from [https://maven.apache.org/guides/introduction/introduction-to
<td align="left">javadoc</td></tr>
</table>
}}}
```
The top-level should hold license, readme, and build.xml.
== Logging ==
## Logging
Metrics' Java projects use SLF4J throughout.
Use the efficient style for parametrized logging statements as explained [http://logback.qos.ch/manual/architecture.html#parametrized here].
Use the efficient style for parametrized logging statements as explained [here](http://logback.qos.ch/manual/architecture.html#parametrized).
Usage example:
...
...
@@ -108,10 +107,9 @@ Log messages are written to loggers. The usual logger is identified by the simp
== Coding Style
This style guide is derived from [https://google.github.io/styleguide/javaguide.html Google's Java Style Guide], which is licensed under [https://github.com/google/styleguide CC-By 3.0 License]. The exact git revision used as basis can be found [https://github.com/google/styleguide/commit/7969290bacb1965d09677a79d523b4871c9d039c here].
This style guide is derived from [Google's Java Style Guide](https://google.github.io/styleguide/javaguide.html), which is licensed under [CC-By 3.0 License](https://github.com/google/styleguide). The exact git revision used as basis can be found [here](https://github.com/google/styleguide/commit/7969290bacb1965d09677a79d523b4871c9d039c).
{{{
#!html
```
<h2>Metrics Team Java Coding Style</h2>
<div class="change">Last changed: May, 2016</div>
<table border="0">
...
...
@@ -908,4 +906,4 @@ what the term "canonical name" means!</p><a name="s7.3.2-javadoc-exception-overr
<p>Javadoc is not always present on a method that overrides a supertype method.
