Free cookie consent management tool by TermsFeed Policy Generator

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


Ignore:
Timestamp:
01/15/11 20:47:48 (14 years ago)
Author:
abeham
Comment:

brought developers guidelines up to date, corrected some links, edited some text

Legend:

Unmodified
Added
Removed
Modified

  • Documentation/DevelopmentCenter/DeveloperGuidelines

    v14 v15  
    88
    99== 2. Coding Standards ==
    10 HeuristicLab code should be conform to the guidelines described in [http://msdn.microsoft.com/en-us/library/ms229042.aspx Design Guidelines for Developing Class Libraries].
     10!HeuristicLab code should be conform to the guidelines described in [http://msdn.microsoft.com/en-us/library/ms229042.aspx Design Guidelines for Developing Class Libraries].
    1111
    1212To 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.
    … …  
    2929   * Interfaces start with an `I` (e.g. `IItem`, `IOperator`).
    3030   * Abstract base classes are not suffixed by `Base` (e.g. `Item`, `Operator`, `Engine`).
    31    * The name of each HeuristicLab plugin starts with `HeuristicLab`.
     31   * The name of each !HeuristicLab plugin starts with `HeuristicLab`.
    3232   * 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`).
     33   * 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`).
    3434   * Plugins can be structured hierarchically (e.g. `HeuristicLab.Operators` and `HeuristicLab.Operators.Programmable`).
    3535   * Sub-namespaces can be used to structure the source files in a plugin.
    3636   * Each plugin is represented by a component in Trac.
    37    * The leading `HeuristicLab.` is omitted in Trac component names.
     37   * The leading string `HeuristicLab.` is omitted in Trac component names.
    3838   * 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`).
    3939
    40 A source code example of well formatted HeuristicLab code is available [wiki:DevelopersGuidelinesSourceExample here].
     40A source code example of well formatted !HeuristicLab code is available [wiki:DevelopersGuidelinesSourceExample here].
    4141
    4242== 3. Versioning System ==
    43 Source 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.
     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.
    4444
    4545For 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].
    … …  
    5151     * contains all project documentation files (API documentation, license, presentations, etc.)
    5252   * `sources`
    53      * contains solution files, scripts and applications required for building HeuristicLab
     53     * contains solution files, scripts and applications required for building !HeuristicLab
    5454     * plugin folders
    55        * each HeuristicLab plugin has its own folder
     55       * each !HeuristicLab plugin has its own folder
    5656       * the folder name has to be identical to the name of the plugin (e.g. `HeuristicLab.Data`)
    5757       * each plugin folder contains sub-folders for each major and/or minor version of the plugin (e.g. `3.3`)
    … …  
    6464       * the name of a feature/exploration branch has to be descriptive
    6565       * 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
     66       * before merging a branch into the trunk, a comprehensive code review has to be done by at least one of the [DevelopersTeam HeuristicLab architects]
    6767       * a developer who created a branch is responsible for deleting it again
    6868     * release branches
    6969       * are used to prepare release versions
    7070       * are used to store old versions of plugins
    71        * the folder name of a release branch has to be identical to the major and minor version number (e.g. 3.1) (cf. [wiki:DevelopmentGuidelines#Versioning Versioning])
     71       * the folder name of a release branch has to be identical to the major and minor version number (e.g. 3.1) (cf. [#a4.Versioning Versioning])
    7272 * `tags`
    73    * contain a folder for each HeuristicLab release bundle (tag)
     73   * contain a folder for each !HeuristicLab release bundle (tag)
    7474   * it is not allowed to commit to tags
    75    * 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])
     75   * the folder name of a tag has to be identical to the whole version number (e.g. 3.1.0.304) (cf. [#a4.Versioning Versioning])
    7676
    7777=== 3.2. Guidelines for Working with the HeuristicLab SVN Repository ===
    … …  
    8282   * each commit message must contain the ticket number of the corresponding Trac ticket (e.g. "(!#1)")
    8383 * repository content
    84    * the repository has to contain all files necessary for compiling HeuristicLab
     84   * the repository has to contain all files necessary for compiling !HeuristicLab
    8585   * automatically generated files (object files, assemblies, !AssemblyInfo.cs, etc.) are not stored in the repository
    8686   * files containing user specific settings are not stored in the repository (e.g. *.suo, *.user)
    … …  
    8989   * each developer can create a new exploration branch at any time
    9090   * new release branches for a plugin can be crated by the head developer of that plugin only
    91    * new tags are created by the head developer of HeuristicLab only
     91   * new tags are created by the head developer of !HeuristicLab only
    9292
    9393== 4. Versioning ==
    94 All plugins and all release bundles of HeuristicLab have a version number following the schema `Major.Minor.Build.Revision`:
     94All plugins and all release bundles of !HeuristicLab have a version number following the schema `Major.Minor.Build.Revision`:
    9595 * `Major` and `Minor`
    96    * 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
     96   * 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
    9797   * when incrementing the major version number of a plugin, the minor version number has to be set back to 0
    98    * 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`)
     98   * 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`)
    9999   * all major and minor versions of a plugin are kept in the repository and have to be functional in order to assure backwards compatibility
    100100 * `Build`
    … …  
    105105 * `Revision`
    106106   * represents the last revision, in which the component (assembly) has been changed or in which a version has been released
    107    * when compiling assemblies the revision number is automatically extracted from the Subversion repository (cf. [wiki:DevelopmentGuidelines#SubWCRev Automatic Extraction of the Current Revision Number])
    108    * when creating a new release bundle of the whole HeuristicLab system (tag) the revision number has to be set manually
     107   * when compiling assemblies the revision number is automatically extracted from the Subversion repository (cf. [#a4.1.SubWCRev Automatic Extraction of the Current Revision Number])
     108   * when creating a new release bundle of the whole !HeuristicLab system (tag) the revision number has to be set manually
    109109
    110110=== 4.1. Automatic Extraction of the Current Revision Number === #SubWCRev
    … …  
    131131 * explanation of the information stored in each ticket:
    132132   * Status
    133      * `new`
     133     * `new` and `assigned`
     134       * represent tickets that have just entered, but have not yet been picked up by a developer
     135       * 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
    134136       * each new ticket is assigned automatically to the developer of the corresponding component or manually to any other developer
    135      * `assigned`
    136        * tickets that are assigned to another developer get the status `assigned`
    137137     * `accepted`
    138138       * tickets that are currently processed by a developer get the status `accepted`
    139139       * the ticket status has to be set manually by the developer before starting to work on the ticket
    140        * if working on a ticket is suspended for a longer period of time without closing the ticket, the status has to be reset to `assigned` (in that way it is assured that accepted tickets represent exactly those tickets, on which developers are currently working)
     140       * if the ticket is assigned a release milestone, it appears under "Waiting for completion", otherwise it is "Under development"
     141     * `reviewing`
     142       * represents tickets of which the implemented work is being reviewed by another developer
     143       * 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
     144     * `readytorelease`
     145       * represents tickets that are release-ready, meaning that the work was implemented, tested, and reviewed
     146       * Tickets are only closed with "done" when a release is being made and remain open until the date of the release
    141147     * `closed`
    142148       * tickets which are resolved get the status `closed`
    143149       * developers have to provide an explanation for closing a ticket
    144        * possible resolutions for closing a ticket are `fixed` (work done), `invalid` (invalid ticket), `wontfix` (ticket will not be resolved), `duplicate` (another ticket has already been created for that issue), `worksforme` (issue could not be reproduced)
    145        * when closing a ticket with another explanation as `fixed`, the developer has to provide a comprehensive explanation
    146      * `reopened`
    147        * when a ticket is reopened again, the status is set to `reopened`
    148        * when reopening a ticket, the responsible developer is removed and the ticket has to be assigned again
     150       * 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)
     151       * when a ticket is closed without being `done`, the developer has to provide a comprehensive explanation
     152     * ~~`reopened`~~
     153       * the ability to reopen a ticket was removed
     154       * if an issue was previously closed, but still remains an issue a new ticket should be created referencing the other one
    149155   * Type
    150156     * `defect`
    … …  
    157163       * other (administrative) tasks which are not associtated with programming directly (e.g. generating documentation, creating release branches, etc.)
    158164   * Priority
    159      * the following priorities are available to classify tickets: `blocker` (priority 1), `critical` (priority 2), `major` (priority 3), `minor` (priority 4), `trivial` (priority 5)
     165     * the priority is used to rank the tickets in the backlog
     166     * the following priorities are available to classify tickets: `highest` (priority 1), `high` (priority 2), `medium` (priority 3), `low` (priority 4), `lowest` (priority 5)
    160167     * classification of a ticket's priority has to be done by the user who reports the ticket
    161168   * Milestone
    162169     * a ticket has to be associated with a milestone
    163      * milestones represent phases of the development of HeuristicLab
    164      * usually a milestone is associated with the version of a HeuristicLab release bundle
     170     * if the issue is targeted for release, it should be assigned a release milestone, otherwise the milestone `HeuristicLab x.x.x` should be chosen and it becomes part of the backlog
     171     * milestones represent iterations in the development of !HeuristicLab
     172     * usually a milestone is associated with the version of a !HeuristicLab release bundle
    165173   * Component
    166174     * a ticket has to be associated with a component (i.e. a plugin)
    167175     * the name of a component has to be identical to the name of the namespace or the plugin of that component (the leading "`HeuristicLab.`" is omitted)
     176     * if no component is suitable or if the component is unknown `General` should be used
    168177   * Version
    169      * each ticket has to be associated with a version number of HeuristicLab
    170      * usually the version number corresponds to the milestone
     178     * each ticket has to be associated with a version number of !HeuristicLab
     179     * typically the ticket gets the version in which the described issue appeared
     180     * the version of the ticket will be changed once the resolution is set to `done` to reflect the version in which the issue was fixed
     181     * for exploration and prototyping, branches may be created and tickets may get the version `branch` indicating that the development is not affecting the trunk
    171182
    172183== 6. Documentation ==
    173184=== 6.1. Wiki ===
    174 The Trac wiki system is used for documenting the development of HeuristicLab. A description of the Trac wiki syntax is available at WikiFormatting.
     185The Trac wiki system is used for documenting the development of !HeuristicLab. A description of the Trac wiki syntax is available at WikiFormatting.
    175186
    176187=== 6.2. Source Code ===
    … …  
    179190Additionally, 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].
    180191
    181 == 7. Frequent Mistakes ==
    182 
    183  * Use `Environment.NewLine` instead of the string constant "\n".
    184  * Use `Path.Combine()` instead of string concatenation (with `\` or `/`) to combine directory and file names.
    185  * Throw and catch specific exceptions, don't catch generic exceptions ~~`try { ... } catch(Exception ex) {}`~~
    186  * Use a finally block to make sure that the state of the program is consistent even when Exceptions are thrown.
    187  * Set the mouse pointer back to normal in a finally {... } block.
    188  * Use `string.Empty` instead of the string constant `""`;
    189  * Use `string.IsEmptyOrNull(a)` instead of `if(a!=null && a!="")`
    190  * Check for `InvokeRequired` in methods that manipulate GUI elements in controls.
    191  * Instantiate all objects of classes implementing `IDisposable` with the `using(...) { ... }` statement to make sure the object is disposed correctly.
    192  * When possible use LINQ syntax instead of extension methods for LINQ expressions.
     192== 7. Coding Recommendations ==
     193
     194 * use `Environment.NewLine` instead of the string constant `"\n"`
     195 * use `Path.Combine()` instead of string concatenation (with `\` or `/`) to combine directory and file names
     196 * throw and catch specific exceptions, don't catch generic exceptions ~~`try { ... } catch(Exception ex) {}`~~
     197 * use a finally block to make sure that the state of the program is consistent even when Exceptions are thrown
     198 * if the mouse pointer was changed, set the mouse pointer back to normal in a finally {... } block
     199 * use `string.Empty` instead of the string constant `""`
     200 * use `string.IsEmptyOrNull(a)` instead of `if(a!=null && a!="")`
     201 * check for `InvokeRequired` in methods that manipulate GUI elements in controls
     202 * instantiate all objects of classes implementing `IDisposable` with the `using(...) { ... }` statement to make sure the object is disposed correctly
     203 * when possible use LINQ syntax instead of extension methods for LINQ expressions
    193204
    194205== 8. Final Remarks ==