= HeuristicLab Development Guidelines = == General == * any documentation has to be written in English (this includes all documents, wiki-pages, commit messages, code comments, ticket descriptions, etc.) * names of plugins, namespaces, classes, structs, enums, methods, properties, variables, etc. are in English * C# 3.0 is used as programming language * HeuristicLab is based on the Microsoft .NET Framework 3.5 SP1 ---- == Software == === Runtime Environment === * [http://www.microsoft.com/downloads/details.aspx?familyid=333325FD-AE52-4E35-B531-508D977D32A6&displaylang=en Microsoft .NET Framework 3.5] * [http://www.microsoft.com/downloads/details.aspx?familyid=AB99342F-5D1A-413D-8319-81DA479AB0D7&displaylang=de Microsoft .NET Framework 3.5 SP1] === Development Environment === * Microsoft Visual Studio 2008 Professional Edition * [http://www.microsoft.com/downloads/details.aspx?FamilyID=fbee1648-7106-44a7-9649-6d9f6d58056e&DisplayLang=de Microsoft Visual Studio 2008 SP1] === Versioning System === * [http://subversion.tigris.org/ Subversion 1.4.2] * [http://tortoisesvn.net/ TortoiseSVN 1.5.0] === Issue Tracking and Wiki === * [http://trac.edgewall.org/ Trac 0.12] === API Documentation === * [http://www.codeplex.com/Sandcastle Sandcastle] * [http://www.codeplex.com/SHFB Sandcastle Help File Builder] ---- == Coding Conventions == 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]. 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. === Indentation === * 2 spaces, no tabs === New Lines / 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 === Naming Conventions === * `CamelCase` for all identifiers * do not use "_" in identifiers * do not use "Hungarian Notation" (e.g. `iCount` for an int counter or `dFactor` for a double factor) * casing * classes, interfaces, properties, and methods start with an uppercase letter (e.g. `Sheep`, `Weight`, `LookABitSilly`) * fields, method parameters, and local variables start with a lowercase letter (e.g. `sheep`, `weight`, `i`) * names * interfaces start with an `I` (e.g. `IItem`, `IOperator`) * ~~abstract base classes end with `Base` (e.g. `ItemBase`, `OperatorBase`)~~ (this convention has been abandoned with HeuristicLab 3.3) * the name of a plugin has to be identical to the project name and the namespace of the plugin (e.g. `HeuristicLab.Data`) * the name of each HeuristicLab plugin starts with "`HeuristicLab.`" * in order to structure plugins hierarchically, sub-namespaces can be used (e.g. `HeuristicLab.Operators` and `HeuristicLab.Operators.Programmable`) * each plugin is represented as a component in Trac * for Trac component names the leading "`HeuristicLab.`" is omitted A source code example of well formatted HeuristicLab code is available at SourceExample. ---- == Versioning System == 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. For 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]. === Repository Layout === * `trunk` * contains the main development branch (trunk) * `documentation` * contains all project documentation files (API documentation, license, presentations, etc.) * `setup` * contains all files to build the HeuristicLab installer * `sources` * `HeuristicLab.sln` * main solution file containing all projects * `PreBuildEvent.cmd` * commands executed each time before compiling HeuristicLab (cf. [wiki:DevelopmentGuidelines#SubWCRev Automatic Extraction of the Current Revision Number]) * project folders * each project (plugin) of HeuristicLab has its own folder * the folder name has to be identical to the namespace of the project (e.g. `HeuristicLab.Data`) * `branches` * contains a folder for each development branch * there are two different kinds of branches: * exploration branches * are used to explore and carry out major changes that effect large parts of the system * each developer is free to create a new exploration branch at any time * the name of an exploration branch has to be descriptive * the developer who created the branch is responsible for deleting it again after exploration is finished * release branches * are used to prepare release versions * are used to store old versions of plugins * 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]) * `tags` * contain a folder for each HeuristicLab release bundle (tag) * it is not allowed to commit to tags * 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]) === Guidelines for Working with the HeuristicLab SVN Repository === * all projects in the trunk have to be compilable in each revision * commit messages * each commit has to have a description (commit message) * WikiFormatting has to be used to format commit messages * each commit message must contain the ticket number of the corresponding Trac ticket (e.g. "(!#1)") * repository content * the repository has to contain all files necessary for compiling HeuristicLab * automatically generated files (object files, assemblies, !AssemblyInfo.cs, etc.) are not stored in the repository * files containing user specific settings are not stored in the repository (e.g. *.suo, *.user) * 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 ---- == 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 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 * when compiling assemblies the revision number is automatically extracted from the Subversion repository (cf. [wiki:DevelopmentGuidelines#SubWCRev Automatic Extraction of the Current Revision Number]) * when creating a new release bundle of the whole HeuristicLab system (tag) the revision number has to be set manually === Automatic Extraction of the Current Revision Number === #SubWCRev The 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: {{{ 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`. ---- == Issue Tracking == The 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. Further information about Trac can be found in the [wiki:TracGuide Trac User and Administration Guide]. === Guidelines for Working with Trac === * all development steps have to be represented by tickets * 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` * each new ticket is assigned automatically to the developer of the corresponding component or manually to any other developer * `assigned` * tickets that are assigned to another developer get the status `assigned` * `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 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) * `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 `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) * when closing a ticket with another explanation as `fixed`, the developer has to provide a comprehensive explanation * `reopened` * when a ticket is reopened again, the status is set to `reopened` * when reopening a ticket, the responsible developer is removed and the ticket has to be assigned again * Type * `defect` * bug in a component * `enhancement` * improvement or extension of the existing functionality of a component * `feature request` * new component or new functionality of an existing component * `task` * other (administrative) tasks which are not associtated with programming directly (e.g. generating documentation, creating release branches, etc.) * Priority * the following priorities are available to classify tickets: `blocker` (priority 1), `critical` (priority 2), `major` (priority 3), `minor` (priority 4), `trivial` (priority 5) * classification of a ticket's priority has to be done by the user who reports the ticket * Milestone * a ticket has to be associated with a milestone * milestones represent phases of the development of HeuristicLab * usually a milestone is associated with the version of a HeuristicLab release bundle * Component * a ticket has to be associated with a component (i.e. a plugin) * 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) * Version * each ticket has to be associated with a version number of HeuristicLab * usually the version number corresponds to the milestone ---- == Documentation == === Wiki === The Trac wiki system is used for documenting the development of HeuristicLab. A description of the Trac wiki syntax is available at WikiFormatting. === Source Code === Source code is commented using single- or multi-line comments in English. Additionally, 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]. ---- == Frequent Mistakes == * Use `Environment.NewLine` instead of the string constant "\n". * Use `Path.Combine()` instead of string concatenation (with `\` or `/`) to combine directory and file names. * Throw and catch specific exceptions, don't catch generic exceptions ~~`try { ... } catch(Exception ex) {}`~~ * Use a finally block to make sure that the state of the program is consistent even when Exceptions are thrown. * Set the mouse pointer back to normal in a finally {... } block. * Use `string.Empty` instead of the string constant `""`; * Use `string.IsEmptyOrNull(a)` instead of `if(a!=null && a!="")` * Check for `InvokeRequired` in methods that manipulate GUI elements in controls. * Instantiate all objects of classes implementing `IDisposable` with the `using(...) { ... }` statement to make sure the object is disposed correctly. * When possible use LINQ syntax instead of extension methods for LINQ expressions. ---- == Final Remarks == Use your brain!