Code & design guidelines

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

Eclipse workspace setup

At the project root, 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 Apache Log4J2
• 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

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