Changes between Version 13 and Version 14 of Documentation/DevelopmentCenter/DeveloperGuidelines


Ignore:
Timestamp:
08/10/10 03:22:45 (9 years ago)
Author:
swagner
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • Documentation/DevelopmentCenter/DeveloperGuidelines

    v13 v14  
     1[[PageOutline]]
    12= HeuristicLab Development Guidelines =
    23
    3 == General ==
    4  * any documentation has to be written in English (this includes all documents, wiki-pages, commit messages, code comments, ticket descriptions, etc.)
    5  * names of plugins, namespaces, classes, structs, enums, methods, properties, variables, etc. are in English
    6  * C# 3.0 is used as programming language
    7  * HeuristicLab is based on the Microsoft .NET Framework 3.5 SP1
     4== 1. General ==
     5 * Any documentation has to be written in English. This includes all documents, wiki-pages, commit messages, code comments, ticket descriptions, ...
     6 * Names of plugins, namespaces, classes, structs, enums, methods, properties, variables, ... are in English.
     7 * C# is used as programming language.
    88
    9 ----
     9== 2. Coding Standards ==
     10HeuristicLab code should be conform to the guidelines described in [http://msdn.microsoft.com/en-us/library/ms229042.aspx Design Guidelines for Developing Class Libraries].
    1011
    11 == Software ==
    12 === Runtime Environment ===
    13  * [http://www.microsoft.com/downloads/details.aspx?familyid=333325FD-AE52-4E35-B531-508D977D32A6&displaylang=en Microsoft .NET Framework 3.5]
    14  * [http://www.microsoft.com/downloads/details.aspx?familyid=AB99342F-5D1A-413D-8319-81DA479AB0D7&displaylang=de Microsoft .NET Framework 3.5 SP1]
     12To ensure consistent formatting of the source code, developers should use identical settings for the Visual Studio Text Editor. The [attachment:"Visual Studio 2010 text editor settings.vssettings" appropriate settings] are attached to this page and should be imported in Visual Studio.
    1513
    16 === Development Environment ===
    17  * Microsoft Visual Studio 2010
    18 
    19 === Versioning System ===
    20  * [http://subversion.tigris.org/ Subversion 1.4.2]
    21  * [http://tortoisesvn.net/ TortoiseSVN 1.5.0]
    22 
    23 === Issue Tracking and Wiki ===
    24  * [http://trac.edgewall.org/ Trac 0.12]
    25 
    26 === API Documentation ===
    27  * [http://www.codeplex.com/Sandcastle Sandcastle]
    28  * [http://www.codeplex.com/SHFB Sandcastle Help File Builder]
    29 
    30 ----
    31 
    32 == Coding Conventions ==
    33 HeuristicLab code has to be conform to the guidelines described in [http://msdn.microsoft.com/en-us/library/ms229042.aspx Design Guidelines for Developing Class Libraries].
    34 
    35 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.
    36 
    37 === Indentation ===
     14=== 2.1. Indentation ===
    3815 * 2 spaces, no tabs
    3916
    40 === New Lines / Blocks ===
    41  * opening braces ("{") are on the same line of the statement which opens the block
    42  * closing braces ("}") are on a new line after the last statement of the block
     17=== 2.2. New Lines and Blocks ===
     18 * Opening braces (`{`) are on the same line of the statement which opens the block.
     19 * Closing braces (`}`) are on a new line after the last statement of the block.
    4320
    44 === Naming Conventions ===
    45  * `CamelCase` for all identifiers
    46    * do not use "_" in identifiers
    47    * do not use "Hungarian Notation" (e.g. `iCount` for an int counter or `dFactor` for a double factor)
    48  * casing
    49    * classes, interfaces, properties, and methods start with an uppercase letter (e.g. `Sheep`, `Weight`, `LookABitSilly`)
    50    * fields, method parameters, and local variables start with a lowercase letter (e.g. `sheep`, `weight`, `i`)
    51  * names
    52    * interfaces start with an `I` (e.g. `IItem`, `IOperator`)
    53    * ~~abstract base classes end with `Base` (e.g. `ItemBase`, `OperatorBase`)~~ (this convention has been abandoned with HeuristicLab 3.3)
    54    * the name of a plugin has to be identical to the project name and the namespace of the plugin (e.g. `HeuristicLab.Data`)
    55    * the name of each HeuristicLab plugin starts with "`HeuristicLab.`"
    56    * in order to structure plugins hierarchically, sub-namespaces can be used (e.g. `HeuristicLab.Operators` and `HeuristicLab.Operators.Programmable`)
    57    * each plugin is represented as a component in Trac
    58    * for Trac component names the leading "`HeuristicLab.`" is omitted
     21=== 2.3. Naming ===
     22 * All identifiers are written in !CamelCase.
     23   * Do not use `_` in identifiers.
     24   * Do not use Hungarian notation (e.g. `iCount` for an int counter or `dFactor` for a double factor).
     25 * Casing:
     26   * Classes, interfaces, properties, and methods start with an uppercase letter (e.g. `Sheep`, `Weight`, `LookABitSilly`).
     27   * Fields, method parameters, and local variables start with a lowercase letter (e.g. `sheep`, `weight`, `i`).
     28 * Names:
     29   * Interfaces start with an `I` (e.g. `IItem`, `IOperator`).
     30   * Abstract base classes are not suffixed by `Base` (e.g. `Item`, `Operator`, `Engine`).
     31   * The name of each HeuristicLab plugin starts with `HeuristicLab`.
     32   * The name of a plugin has to be identical to the project name and the namespace of the plugin (e.g. `HeuristicLab.Data`).
     33   * Project names are suffixed with their major and minor version number (e.g. `HeuristicLab.Data-3.3`).
     34   * Plugins can be structured hierarchically (e.g. `HeuristicLab.Operators` and `HeuristicLab.Operators.Programmable`).
     35   * Sub-namespaces can be used to structure the source files in a plugin.
     36   * Each plugin is represented by a component in Trac.
     37   * The leading `HeuristicLab.` is omitted in Trac component names.
     38   * Data components that correspond to a property should have the same name as the property and are not prefixed by `my` (e.g. in `Item` `filename` is the correct name for the data component of the `Filename` property and not `myFilename`).
    5939
    60 A source code example of well formatted HeuristicLab code is available at SourceExample.
     40A source code example of well formatted HeuristicLab code is available [wiki:DevelopersGuidelinesSourceExample here].
    6141
    62 ----
    63 
    64 == Versioning System ==
    65 Source code and other documents are kept in a Subversion repository available at [https://sources.heuristiclab.com/hl3/core https://sources.heuristiclab.com/hl3/core]. Anonymous read-only access is available using the user name "anonymous" and an empty password. If you want to contribute to the HeuristicLab project and need write access, please write an e-mail to [mailto:support@heuristiclab.com support@heuristiclab.com]. All HeuristicLab developers have full write access to the whole repository.
     42== 3. Versioning System ==
     43Source code and other documents are kept in the HeuristicLab Subversion repository available at http://dev.heuristiclab.com/svn/hl/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.
    6644
    6745For an introduction to Subversion, please take a look at the free book [http://svnbook.red-bean.com/ Version Control with Subversion] and the [http://tortoisesvn.net/docs/release/TortoiseSVN_en/index.html Online Documentation] of the Subversion client [http://tortoisesvn.net/ TortoiseSVN].
    6846
    69 === Repository Layout ===
     47=== 3.1. Repository Layout ===
    7048 * `trunk`
    7149   * contains the main development branch (trunk)
    7250   * `documentation`
    7351     * contains all project documentation files (API documentation, license, presentations, etc.)
    74    * `setup`
    75      * contains all files to build the HeuristicLab installer
    7652   * `sources`
    77      * `HeuristicLab.sln`
    78        * main solution file containing all projects
    79      * `PreBuildEvent.cmd`
    80        * commands executed each time before compiling HeuristicLab (cf. [wiki:DevelopmentGuidelines#SubWCRev Automatic Extraction of the Current Revision Number])
    81      * project folders
    82        * each project (plugin) of HeuristicLab has its own folder
    83        * the folder name has to be identical to the namespace of the project (e.g. `HeuristicLab.Data`)
     53     * contains solution files, scripts and applications required for building HeuristicLab
     54     * plugin folders
     55       * each HeuristicLab plugin has its own folder
     56       * the folder name has to be identical to the name of the plugin (e.g. `HeuristicLab.Data`)
     57       * each plugin folder contains sub-folders for each major and/or minor version of the plugin (e.g. `3.3`)
    8458 * `branches`
    8559   * contains a folder for each development branch
    86    * there are two different kinds of branches:
    87      * exploration branches
    88        * are used to explore and carry out major changes that effect large parts of the system
    89        * each developer is free to create a new exploration branch at any time
    90        * the name of an exploration branch has to be descriptive
    91        * the developer who created the branch is responsible for deleting it again after exploration is finished
     60   * there are three different kinds of branches:
     61     * feature/exploration branches
     62       * are used to develop new plugins or to explore and carry out major changes that effect large parts of the system
     63       * each developer is free to create new feature/exploration branches at any time
     64       * the name of a feature/exploration branch has to be descriptive
     65       * new plugins should be developed in a feature branch first
     66       * before merging a branch into the trunk, a comprehensive code review has to be done by at least one of the HeuristicLab architects
     67       * a developer who created a branch is responsible for deleting it again
    9268     * release branches
    9369       * are used to prepare release versions
     
    9975   * the folder name of a tag has to be identical to the whole version number (e.g. 3.1.0.304) (cf. [wiki:DevelopmentGuidelines#Versioning Versioning])
    10076
    101 === Guidelines for Working with the HeuristicLab SVN Repository ===
     77=== 3.2. Guidelines for Working with the HeuristicLab SVN Repository ===
    10278 * all projects in the trunk have to be compilable in each revision
    10379 * commit messages
     
    11591   * new tags are created by the head developer of HeuristicLab only
    11692
    117 ----
    118 
    119 == Versioning ==
     93== 4. Versioning ==
    12094All plugins and all release bundles of HeuristicLab have a version number following the schema `Major.Minor.Build.Revision`:
    12195 * `Major` and `Minor`
     
    134108   * when creating a new release bundle of the whole HeuristicLab system (tag) the revision number has to be set manually
    135109
    136 === Automatic Extraction of the Current Revision Number === #SubWCRev
     110=== 4.1. Automatic Extraction of the Current Revision Number === #SubWCRev
    137111The tool [http://tortoisesvn.net/docs/release/TortoiseSVN_en/tsvn-subwcrev.html SubWCRev] of TortoiseSVN is used to extract the revision number of the last change of a plugin. SubWCRev is executed by the command [source:trunk/PreBuildEvent.cmd PreBuildEvent.cmd] which has to be set as pre-build event in each project in the following way:
    138112{{{
     
    142116SubWCRev replaces the placeholders `$WCREV$` and `$WCNOW$` in the frame file `AssemblyInfo.frame` of the project and creates the file `AssemblyInfo.cs`.
    143117
    144 ----
    145 
    146 == Issue Tracking ==
     118== 5. Issue Tracking ==
    147119The issue tracking system [http://trac.edgewall.org/ Trac] is used to manage the HeuristicLab development process. The HeuristicLab Trac environment is available at [https://sources.heuristiclab.com/trac/hl3/core 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.
    148120
    149121Further information about Trac can be found in the [wiki:TracGuide Trac User and Administration Guide].
    150122
    151 === Guidelines for Working with Trac ===
     123=== 5.1. Guidelines for Working with Trac ===
    152124 * all development steps have to be represented by tickets
    153125 * before working on a plugin, a ticket has to be created and accepted by the developer
     
    198170     * usually the version number corresponds to the milestone
    199171
    200 ----
    201 
    202 == Documentation ==
    203 === Wiki ===
     172== 6. Documentation ==
     173=== 6.1. Wiki ===
    204174The Trac wiki system is used for documenting the development of HeuristicLab. A description of the Trac wiki syntax is available at WikiFormatting.
    205175
    206 === Source Code ===
     176=== 6.2. Source Code ===
    207177Source code is commented using single- or multi-line comments in English.
    208178
    209179Additionally, each type (class, enum, struct, etc.) and each public or protected method, property, or variable has to be documented using a C# XML comment. These comments are used to generate the API documentated using the tools [http://www.codeplex.com/Sandcastle Sandcastle] and [http://www.codeplex.com/SHFB Sandcastle Help File Builder]. A description of XML comments and several examples can be found at [http://msdn.microsoft.com/en-us/library/b2s063f7.aspx XML Documentation Comments] of the [http://msdn.microsoft.com/en-us/library/67ef8sbd.aspx C# Programming Guide].
    210180
    211 ----
    212 
    213 == Frequent Mistakes ==
     181== 7. Frequent Mistakes ==
    214182
    215183 * Use `Environment.NewLine` instead of the string constant "\n".
     
    224192 * When possible use LINQ syntax instead of extension methods for LINQ expressions.
    225193
    226 ----
    227 
    228 == Final Remarks ==
     194== 8. Final Remarks ==
    229195Use your brain!