2. Coding Standards

To ensure consistent formatting of the source code, developers should use identical settings for the Visual Studio Text Editor. The appropriate settings​ are attached to this page and should be imported in Visual Studio. Additionally a list of useful Visual Studio 2010 extensions which help to ensure the coding standard, is compiled on this page.

2.1. Indentation

2 spaces, no tabs

2.2. New Lines and Blocks

Opening braces ({) are on the same line of the statement which opens the block.

Closing braces (}) are on a new line after the last statement of the block.

2.3. Naming

All identifiers are written in CamelCase.

Do not use _ in identifiers.

Do not use Hungarian notation (e.g. iCount for an int counter or dFactor for a double factor).

The name of a plugin has to be identical to the project name and the namespace of the plugin (e.g. HeuristicLab.Data).

Project names and their output are suffixed with their major and minor version number (e.g. HeuristicLab.Data-3.3, HeuristicLab.Data-3.3.dll).

Plugins can be structured hierarchically (e.g. HeuristicLab.Operators and HeuristicLab.Operators.Programmable).

Sub-namespaces can be used to structure the source files in a plugin.

Each plugin is represented by a component in Trac.

The leading string HeuristicLab. is omitted in Trac component names.

Data components that correspond to a property should have the same name as the property and are not prefixed by my (e.g. in Itemfilename is the correct name for the data component of the Filename property and not myFilename).

A source code example of well formatted HeuristicLab code is available here?.

2.4 Unit Tests

Unit Tests are to be included in a separate solution called HeuristicLab 3.3 Tests.sln. The project is organized into multiple folders corresponding to the namespaces.

The naming convention for unit tests is [Prefix] ClassName "Test" [MethodName] [CaseDescription]. ClassName can be descriptive and also describe a group of classes (e.g. DeepCloneables), it does not need to correspond to the actual class name. Examples:

DeepCloneablesTestClone

DeepCloneablesTestCloningConstructor

BinaryVectorSinglePointCrossoverTest

OnlineCalculatorsPearsonR2TestRandom

OnlineCalculatorsPearsonR2TestConstant

Each test can be categorized according to several dimensions:

Dimension 1 - via TestCategory attribute (required)

General

Algorithms.*

Encodings.*

Problems.*

Persistence

Samples.*

Dimension 2 via TestCategory attribute (optional)

Essential -> Tests are executed on the builder after each commit (should run reasonably fast)

Dimension 3 - via TestProperty("Time", "") attribute (required)

Short (ca. < 1s)

Medium (ca. < 10s)

Long (>= 10s)

2.5 Visual Studio Extensions & Addons

If you are working as core developer this extension must be installed with the options 'Format Document on save' and 'Remove and Sort Usings on save' enabled to ensure a consistent source code formatting.

3. Versioning System

Source code and other documents are kept in the HeuristicLab Subversion repository available at ​http://svn.heuristiclab.com/svn/core. Anonymous read-only access is enabled. If you want to contribute to HeuristicLab and therefore need write access to the repository, please write an e-mail to ​support@heuristiclab.com.

the SVN property svn:ignore has to be set to prevent that files are added accidentally (predefined property values for solution, project, and properties folders are attached to this page and can be imported)

branches and tags

each developer can create a new exploration branch at any time

new release branches for a plugin can be crated by the head developer of that plugin only

new tags are created by the head developer of HeuristicLab only

4. Versioning

All plugins and all release bundles of HeuristicLab have a version number following the schema Major.Minor.Build.Revision:

Major and Minor

in order to distinguish from older versions of HeuristicLab (1.1 and 2.0), all plugins of HeuristicLab 3.x should have a major version number greater or equal to 3

when incrementing the major version number of a plugin, the minor version number has to be set back to 0

the major and minor version numbers have to be included in the assembly name of each HeuristicLab assembly (e.g. HeuristicLab.Data-3.3.dll)

all major and minor versions of a plugin are kept in the repository and have to be functional in order to assure backwards compatibility

Build

the build number is used to identify different versions within the same major and minor version of a plugin

for each new version (major or minor version number increment), the build number has to be set back to 0

all builds within the same major and minor version are considered to be "functionally equivalent"

all builds within the same major and minor version have to be backwards compatible concerning data files

Revision

represents the last revision, in which the component (assembly) has been changed or in which a version has been released

4.1. Automatic Extraction of the Current Revision Number

The tool ​SubWCRev of TortoiseSVN is used to extract the revision number of the last change of a plugin. SubWCRev is executed by the command PreBuildEvent.cmd​ which has to be set as pre-build event in each project in the following way:

cmd /c ""$(SolutionDir)PreBuildEvent.cmd" "$(ProjectDir).""

SubWCRev replaces the placeholders $WCREV$ and $WCNOW$ in the frame file AssemblyInfo.frame of the project and creates the file AssemblyInfo.cs.

5. Issue Tracking

The issue tracking system ​Trac is used to manage the HeuristicLab development process. The HeuristicLab Trac environment is available at ​https://sources.heuristiclab.com/trac/hl3/core. User credentials are identical to those of the Subversion repository. For anonymous access the user "anonymous" and an empty password can be used.

5.1. Guidelines for Working with Trac

before working on a plugin, a ticket has to be created and accepted by the developer

each developer is allowed to assign tickets to other developers, if the ticket is in the responsibility of that developer

development progress has to be documented by ticket comments

for each commit associated with a ticket, a ticket comment has to be written that contains a link to the revision (e.g. "(r304)") and a short description (in combination with the link to the ticket in the commit message, this results in a bijective association of tickets and revisions)

each commit has to be associated with a single ticket

explanation of the information stored in each ticket:

Status

new and assigned

represent tickets that have just entered, but have not yet been picked up by a developer

if the ticket is assigned a release milestone (such as e.g. HeuristicLab 3.3.2) the ticket appears as "Waiting for completion", otherwise it is part of the backlog

each new ticket is assigned automatically to the developer of the corresponding component or manually to any other developer

accepted

tickets that are currently processed by a developer get the status accepted

the ticket status has to be set manually by the developer before starting to work on the ticket

if the ticket is assigned a release milestone, it appears under "Waiting for completion", otherwise it is "Under development"

reviewing

represents tickets of which the implemented work is being reviewed by another developer

A completed ticket should be reviewed by another member of the time to ensure that the work is of high quality and the implemented solution is in accordance with the standards set by the team

readytorelease

represents tickets that are release-ready, meaning that the work was implemented, tested, and reviewed

Tickets are only closed with "done" when a release is being made and remain open until the date of the release

closed

tickets which are resolved get the status closed

developers have to provide an explanation for closing a ticket

possible resolutions for closing a ticket are done (the issue was resolved and released), invalid (the issue described is not an issue), rejected (the issue will not be resolved), duplicate (another ticket has already been created for that issue), worksforme (the issue could not be reproduced), and obsolete (the issue is outdated and no longer relevant)

when a ticket is closed without being done, the developer has to provide a comprehensive explanation

reopened

the ability to reopen a ticket was removed

if an issue was previously closed, but still remains an issue a new ticket should be created referencing the other one