LARA Development

SVN Repository

The LARA code is shared between the developers through a subversion repository (svn). The code is organised in different locations inside the svn: trunk, branches, and tag. Please read the following explanations carefully. For experiments and changes which could have side effects on the code/projects of others please create yourself a branch.

%% Explanation taken from stackoverflow.com (http://stackoverflow.com/questions/16142/what-do-branch-tag-and-trunk-mean-in-subversion-repositories/16163#16163)

Trunk: Trunk would be the main body of development, originating from the the start of the project until the present. It needs to be checked to work before any commit!

Branch: Branch will be a copy of code derived from a certain point in the trunk that is used for applying major changes to the code while preserving the integrity of the code in the trunk. If the major changes work according to plan, they are usually merged back into the trunk.

Tag: Tag will be a point in time on the trunk or a branch that you wish to preserve. The two main reasons for preservation would be that either this is a major release of the software, whether alpha, beta, RC or RTM, or this is the most stable point of the software before major revisions on the trunk were applied.

Development Principles

General

  • As modular as possible (with respect to performance)
  • Prefer small and less complicated methods to big and complicated ones (code better readable)
  • Document changes as you implement them
  • Comments in British English!

Testing

  • Write tests beforehand every new implementation as possible
  • Reach a maximum of code-coverage with unit tests

General Coding Guidelines

Naming Scheme

  • Interfaces: Lara[functionality]
  • Abstract Implementations: AbstractL[functionality]
  • Further classes: L[concrete functionality]

Class Scheme

Classes elements follow this scheme:

  • file comments: brief description of the purpose of the file, author name(s)
  • imports
  • classes/interfaces
    • class/interface comments: brief description of the purpose of the file, author name(s)
    • static attributes
      • public attributes
      • protected attributes
      • private attributes
    • static initializers
      • static methods
    • instance attributes
      • public attributes
      • protected attributes
      • private attributes
    • constructors
      • instance methods grouped first by functionality and second by scope (public-protected-private)
      • declare all variables (unless for loop variables ;-)) at first!
      • initialize variables as early as possible
    • getter/setter methods

Programming Style

  • Numerical constants (literals) should not be coded directly. Use the ParMa framework to deal with parameters!
  • Use protected for attributes possibly relevant to subclasses
  • Comment as much as you can. Use as much JavaDoc comments as you can.
Recommended JavaDoc settings in eclipse
  • But: Avoid duplicating information that is present in (and clear from) the code, since it is too easy for redundant comments to get out of date.

Format Specifications

A eclipse format profile can be downloaded from here

  • Line length should not exceed 90 characters
    • Break after a comma
    • Break before an operator
    • Prefer higher-level breaks to lower-level breaks
    • Align the new line with the beginning of the expression at the same level on the previous line
    • If the above rules lead to confusing code or to code that's squished up against the right margin, just indent 8 spaces instead
    • See here (page 5f) for some helpful examples
  • Declarations
    • One declaration/statement per line
    • Blocks: Open brace "" appears at the end of the same line as the declaration statement, closing brace "" starts a line by itself indented to match its corresponding opening statement.
    • Braces are used around all statements, even singletons, when they are part of a control structure, such as a if-else or for statement. This makes it easier to add statements.
    • See here (page 12ff) for structure of if/else, for, while etc.
  • One blank line should always be used in the following circumstances
    • between methods
    • between the local variables in a method and its first statement
    • before a block or single-line comment
    • between logical sections inside a method to improve readability
  • Blank Spaces:
    • after commas in argument lists
    • between expressions in a for statement
    • binary operators except . should be separated from their operands
    • keyword followed by a parenthesis should be separated by a space
    • casts should be followed by a blank
  • use parentheses liberally in expressions involving mixed operators

Setting up Logging Framework

First, look at Logging to get familiar with LARA's logging facilities.

To allow filtering messages according to packages and classes, it is required to log to a logger specified by class name, at best:

static private Logger logger = Log4jLogger.getLogger(Class.class);

Hint: Define the statement as template in eclipse (Preferences > Java > Editor > Template).

For logging within the code use for instance

logger.info("Test Log").

There are plenty of examples in existing LARA code!

Logging methods may not be forwarded since then the source of logs is not identifiable: The class name cannot be logged. Observing certain components/packages is only possible when logged to a certain logger retrieved by class name (s.o.).

Logger properties are private since every class needs to retrieve its own logger.

Updating this Documentation Site

This documentation site is built using Maven. The format is usually APT which is pretty easy to understand and apply.

The source code of this site including ant scripts to deploy it on sourceforge.net are contained in LARA_Documentation.