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.

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")
• pretty low traffic DEBUG
• high traffic log as TRACE
• 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

Every class with custom equals/hashcode(or something like this) should be tested using EqualsVerifier. In Leshan, this ensures that the equals and hashCode implementations comply with their respective contracts. EqualsVerifier is a library designed specifically for thoroughly testing these methods. To meet these requirements:

• hashCode and equals methods must be declared as final to prevent unexpected behavior in subclasses.
• The equals method should use the instanceof operator to verify the object's type and utilize equals for field-by-field comparison.
• For classes designed to be extended, the canEqual method should be implemented to properly handle equality checks across hierarchies.

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
• Do not hesitate to refer issue in commit summary line using this syntax : GH-${issue_number} (e.g. GH-830)
• Summary line (first commit line) MUST be 72 characters or less.