Code & design guidelines

This page try to collect all the Leshan development rules and good practices.

Configure your IDE.

Most Leshan commiters are using Eclipse IDE, if this is your case, take a look at Eclipse workspace setup. If you are using another IDE, maybe it is able to understand our eclipse-formatter file.

(If you want to add links or documentation for your IDE to this guide, let us know !)

Eclipse workspace setup

At this point, we suppose you already clone the leshan git repository and you get eclipse with egit and m2e.

1. To get default settings (like formatter, on save actions ...), launch : mvn resources:copy-resources@configure-eclipse.
   If your projects are already imported in eclipse, you should close eclipse before.
2. Launch eclipse.
3. Import leshan projects in eclipse (if not already done) :
   • add git repository with egit.
   • imports as maven projects.
4. This should be OK, if you have some build errors, try to clean projects.

The deprecated way

ℹ️ This way is not recommended anyway as maven-eclipse-plugin is no more maintained.

You need to add the M2_REPO to your java classpath variables. To do that you can execute the following command:

mvn -Declipse.workspace=<path-to-eclipse-workspace> eclipse:add-maven-repo

You must to restart eclipse(if it was opened).

You can also do that inside eclipse: From the menu bar, select Window > Preferences. Select the Java > Build Path > Classpath Variables page.

Now, you need to "eclipsify" leshan java projects,so run:

mvn eclipse:eclipse

It will generate the project files and classpath with the correct code formater.

In eclipse just do "File->Import" pick "Existing projects" and point to the directory where you cloned the Leshan project.

Code rules

• license header on every source files
• format using the provided code formatter (.xml for eclipse)
• toString should be implemented using String format
• throw IllegalArgumentException if a given method parameter is not following the contract (like a null value where it's illegal)
• log using SLF4J facade, at rutime use Logback
• log as INFO, WARN, ERROR only low traffic messages (INFO is really only for "ok this component is started" but never for "I replied to this request")
• high traffic log as TRACE or DEBUG
• try hard to keep class and method names small
• javadoc on every class for at least explaining purpose
• javadoc on API public methods
• favour final keyword only for class attributes

Tests

• explicit test name as a sentence in snake case not in camel case: not testSendMessage() but send_a_message_and_expect_a_response()

Build

• use "version" property in pom.xml only to avoid to duplicate it.

Design guidelines

• avoid class hierarchies: http://commandcenter.blogspot.com/2012/06/less-is-exponentially-more.html (search for "taxonomy") or the more javaish: http://www.javaworld.com/article/2073649/core-java/why-extends-is-evil.html
• separate clearly what is API and what is implementation
• try hard to limit dependencies and start-up time
• simple code without comments is always better than convoluted code with a full page of javadoc
• never optimize upfront: "premature optimization is the root of all evil"

Git

• avoid merge commits, rebase your work on top of the master before pushing a pull-request