Difference between revisions of "Software Development Guidelines"

From GreenVulcano Wiki
Jump to: navigation, search
m (Design)
m (Design)
Line 9: Line 9:
 
This section covers common guidelines concerning the design of our software.
 
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) ===
+
=== Clearly separate concerns in your design ===
 +
; A.K.A. : No business and presentation logic mix-up
 
; Importance : HIGH
 
; 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".
 
; 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 (as in: NEVER) hardcode settings or "magic" values (a.k.a. you die if you hardcode settings) ===
+
=== Never hardcode settings or "magic" values ===
 +
; A.K.A. : you die if you do that
 
; Importance : HIGH
 
; 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.
 
; 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.
 
; 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) ===
+
=== Provide a reasonable default for configuration-based software ===
 +
; A.K.A : Convention Over Configuration
 
; Importance: HIGH
 
; 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  
 
; 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 ConfigurationProperties reader shall also have a constructor omitting such parameter, which shall search for "config.properties" in the classpath or current working directory.  
 
; Example: besides having a constructor specifying which file to read, a ConfigurationProperties 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) ===
+
=== Avoid references to your own workspace files ===
 +
; A.K.A. : no "/home/johndoe/projects" on SVN or GIT
 
; Importance : MEDIUM
 
; Importance : MEDIUM
 
; Reason : Every developer has his/her own settings.
 
; Reason : Every developer has his/her own settings.

Revision as of 10:50, 3 January 2016

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.

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 ConfigurationProperties 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.

Naming

Formatting

Versioning