Schleifenbauer Developer Conventions
------------------------------------

Author: B. Vaessen (Launch IT)

Contents
--------

Introduction
1. Documentation
2. Architecture
3. Sources
4. Tests
5. Misc



Introduction
------------

The Schleifenbauer Developer Community supports developing software for 
Schleifenbauer Power Distribution Units. All sources offered here are 
open source, and contribution is welcome. You can either develop own 
interfaces from scratch, or build on the code already available.

This community is independent from Schleifenbauer. However, this does not 
mean that there will in principle not be any support. An agreement has 
been made to Schleifenbauer, that only so called Certified code can be an 
issue to support. Sources, combined with documentation, examples and 
test code, will be certified in case they meet the conventions stated 
in this document, and have been reviewed and tested by a third party.


1. Documentation
----------------

The documentation should at least describe the following chapters:
* Introduction (Background, Purpose)
* Environment (Language, Compliler, PDU Firmware version etc.)
* How to use / Getting started / Example
* Class/Entity relation diagram
* Information per structure, class or interface
* Information on testing
* Error codes and other important parameters or defines
* Status and future plans


2. Architecture
---------------

* Modelling is done in a well known modelling language, such as UML.
* Concepts are grouped into classes, or if not object oriented, in 
  structures that allow for easy reuse.


3. Sources
----------

* Each class or struct is expected to be in a seperate file
* Each function or method is documented, providing information on the 
  purpose, the parameters and the return value. Preferrably, tags 
  parsable by Doxygen are used. 
* Variable names are never shorter than 3 characters, and if possible 
  describe the purpose by its name.
* At least some minimal kind of error handling is provided. Preferrably, 
  0 means success. Any other standard is fine, as long as it is commented 
  and consequent.
* Proper indentation is used. Please set the editor to use spaces instead 
  of tabs. Preferrably, 4 spaces are used for a tab. Curly brackets 
  are preferrably each printed on new lines:
  if ()
  {
      ...
      ... 
  }
  else
  {
      ...
      ...
  }
* Do not use numbers in the middle of the code, when the meaning is not 
  clear. Use a define, or constant instead, or at least comment these 
  magic numbers. 
* Try to limit the usage of globals, but if you do need them, make sure 
  they can somehow be recognized, by a prefix consequently used.



4. Tests
--------

Before code is subject to certification, some simple method for 
automatic testing is to be provided. The intention is that, before each 
Code Commit, all features are to be confirmed Running and Tested (RTF).
Preferrably, a Test Driven Development (TDD) approach is applied.



5. Misc
-------

Preferred Dateformat: YYYY-MM-DD hh:mm:ss.msec

File formats: Please try to use open text files whenever possible. We prefer
png files over jpg. For documentation containing graphics, html is preferred 
over closed, binary files such as Word documents.

A certified API should generate warnings in case the API is running on a firmware
combination it has never been tested on.