Software Development Guidelines

Introduction

Rationale

The GreenVulcano code base has been growing over time. While the code has traditionally been "reviewed" by one or two people (our historical "good dictators") before submission to public availability, this is becoming less and less the case due to our increasing core development community. Therefore, some self-discipline is needed in order to improve collaboration - and, sometimes, reduce the frustration due to switching from one style to the other between different source files (and often even within the same file).

This is an open, ongoing, collaborative document! If you feel like a new guideline is needed for the project, then:

• Discuss it with senior colleagues to check that it actually makes sense, then
• Add it to this document, in the relevant section.

The good dictators

A dictator is really nothing more than a very senior technical lead. The reason why we use the term dictator is that we as a community take his/her advice very seriously. In fact, one of the few actions having serious consequences for a community member is to contravene an explicit dictator ruling or warning.

Please note:

• The role of our dictators is to preserve the overall quality of our software over time.
• Besides spitting out new rules, dictators are usually willing to discuss non-trivial project-related issues. Do not feel afraid to ask if you feel you need some advice.
• It's a role based on volunteering. Do not voluntarily waste teir time.
• It's a hard job and takes a lot of time, along with a good deal of experience; do propose yourself as a dictator if you feel you can contribute on this account.

You can contact our dictators at dictators@greenvulcano.com [[1]].

Structure of a rule

Each rule has, at least:

• A Name
• An Importance classification:
  • HIGH
  • MEDIUM
  • LOW
  • COSMETIC
• A Reason explaining why you have to comply

And, optionally:

• Suggestions on how to comply with the rule
• Allowed Exceptions to that rule.

Exceptions to a rule

Exceptions are generally said to prove the rule. So there must be a rule for exceptions. How exceptions are dealt with depends on the Importance classification of the rule:

• HIGH: exceptions are not allowed, in any circumstance. Ok, you can ask a dictator, but expect a NO. If, by chance, you get a YES, or even a MAYBE, then probably the rule's importance needs to be degraded to MEDIUM. However, in case an exception ever gets authorized, the exception rule for MEDIUM applies.
• MEDIUM: exceptions are allowed only if authorized by a dictator, and such authorization must be referenced in the code where the rule is infringed, along with the reason for infringement.
• LOW: exceptions are allowed only if authorized by the project's technical lead, and such authorization must be referenced in the code where the rule is infringed.
• COSMETIC: exceptions are not welcome, but tolerated if kept within reason.

Design

This section covers common guidelines concerning the design of our software.

Clearly separate concerns in your design

A.K.A. 

No business and presentation logic mix-up

Importance 

HIGH

Reason 

Whenever possible, our software has to make no assumptions on the context where it runs. As a matter of example: it happened that software originally targeting the desktop needed to be ported to the cloud - it was a bloodshed to separate the actual processing logic from "buttons", "text fields" and "properties".

Never hardcode settings or "magic" values

A.K.A. 

You die if you do that

Importance 

HIGH

Reason 

Your code can (and will) be used in contexts which are totally unknown to you. It will need either to be totally context-independent, or to make all context-related aspects configurable.

Example

A ConfigProperties reader must have a constructor specifying "which" file to read.

Provide a reasonable default for configuration-based software

A.K.A 

Convention Over Configuration

Importance

HIGH

Reason 

We mainly develop middleware. This usually requires a lot of knowledge about the environment the software runs within, which means a lot of configuration. The user may easily feel overwhelmed by having to configure each and every bit. Therefore, when a "default" behavior just makes sense, in absence of a more specific configuration

Example

Besides having a constructor specifying which file to read, a ConfigProperties reader shall also have a constructor omitting such parameter, which shall search for "config.properties" in the classpath or current working directory.

Avoid references to your own workspace files

A.K.A. 

no /home/johndoe/projects on SVN or GIT

Importance 

MEDIUM

Reason 

Every developer has his/her own settings and favourite IDE layouts. If such preferences are placed in a shared, versioned file, a commit war will inevitably start - causing frustration in the entire team/community.

Suggestion 

In order to avoid this, only place common, default settings in the versioned files, and provide a template for unversioned user properties. Then use a smart configuration reader that allows user-specific properties to override the default ones.