This page describes DotSpatial software design principles and project policies related to coding conventions, naming and namespaces, compiling and build settings, unit testing, deployment, etc.
Source Code Management
This project source code is managed through TFS (Team Foundation Server). To use the TFS connection, you need developer permissions. For read only access, use SVN.
- An overarching goal is to develop tools that look and feel like the .NET framework. Therefore we try to follow the standardized .NET convention e.g. as described in The Framework Design Guidelines Book (http://www.amazon.com/Framework-Design-Guidelines-Conventions-Libraries/dp/0321545613)
and as defined by the FxCop tool for Visual Studio or Gendarme for MONO. We also encourage following coding conventions defined by StyleCop.
- All source code files should include the copyright notice header.
- Contributors are encouraged note major code contributions and changes with a date in the header. This is primarily to help recognize contributions.
- Our preferred language for the core components is C#. Extensions and applications can be written in C# or VB.NET or other .NET language.
- U.S. English will be used for all internal documentation, exception strings, enumerations, and ToString methods in the core components. Internationalization will generally occur only at the application level.
- Don't commit broken code.
Naming, Namespaces, Assembly, General Architecture
- DotSpatial is the root of the namespace. Namespaces should be descriptive of function not of sub-project. In other words "Topology" not "NTS". This requires more integration of projects - but will also help meet the goal of a well-integrated project.
- Assemblies should be named to match the associated namespace - e.g. DotSpatial.Topology.dll should contain the DotSpatial.Topology namespace.
- Extensions of a namespace can be compiled to a separate assembly such as DotSpatial.Topology.Foo.dll. Extensions might also include project names such as DotSpatial.Data.Raster.GDAL.dll as a wrapper for the GDAL unmanaged code/data provider.
- Maintain clear separation (e.g. in namespacing and assemblies - following MVVM style) of GUI code from core functionality - this is to help support unit testing as well as UI portability (e.g. use of WPF versus Silverlight versus Windows forms).
- The core libraries including data, topology, tools, interfaces, and controls will not reference or require any external libraries beyond the .net framework.
Compiling and Build Settings
- In Visual Studio 2010 Warning Level should be set to Level 4 and treat warnings as errors (find equivalent setting for Mono). We don't want code that generates lots of warnings.
- Build Configurations: If a specific project contains only managed code, by default we should build using the anycpu compiler switch. The resulting managed module is PE32/agnostic, running on x86 Windows as a 32-bit application and on x64 Windows as a 64-bit
application. Things are different when a project contains methods that call unmanaged code. We really have 2 cases here: If a specific project interoperates with unmanaged code (x86 library) we should build using the x86 compiler switch. The resulting managed
module is PE32/x86, running on x86 Windows as a 32-bit application and on x64 Windows as a WoW64 application. If a specific project interoperates with unmanaged code (x64 library) we should build using the x64 compiler switch. The resulting managed module
is PE32/x64, doesn't run on x86 Windows, and runs on x64 Windows as a x64 application.
- We will write extensive unit tests for all functions to test functionality against appropriate standards.
- Use of multiple data sets for testing.
- Our goal is zip file based deployment. In other words, all current assemblies can be downloaded in a single zip file for use by third party programmers.
- Applications can/should be deployed using an installer (e.g. MSI, Click Once, Inno Setup)
Assembly and Versioning Info
- All Assembly information should be provided in every DotSpatial assembly as follows (either in the VersionInfo.cs, AssemblyInfo.cs, AssemblyInfo.vb):
- <Assembly: AssemblyTitle("DotSpatial.MyAssembly")>
- <Assembly: AssemblyDescription("Brief statement of purpose of the assembly.")>
- <Assembly: AssemblyCompany("DotSpatial Project Team")>
- <Assembly: AssemblyProduct("DotSpatial - www.dotspatial.org")>
- <Assembly: AssemblyCopyright("Copyright (C) 1998-2013 DotSpatial Project Team")>
- <Assembly: AssemblyTrademark("DotSpatial is a trademark of the DotSpatial Project Team")>
- <Assembly: AssemblyConfiguration("32 bit versus 64 bit or any CPU build/release")
- <Assembly: AssemblyCulture(if non-gui then state "Culture Neutral", otherwise state approach for handling languages)
- <Assembly: ComVisible(false)>
- <Assembly: CLSCompliant(true)>
- <Assembly: AssemblyVersion(major.minor)> This is where other assemblies that reference the assembly will look. If this number changes, other assemblies have to update their references to this assembly! The AssemblyVersion is required.
- <Assembly: AssemblyFileVersion(major.minor.revision.build)>Used for deployment. Increase this number for every deployment. It is used by setup programs. Use it to mark assemblies that have the same AssemblyVersion, but are generated from different
- <Assembly: AssemblyInformationalVersion(Friendly Version Name)>This is the version we use when talking to users or for display on the website. This version can be a string, like '1.0 Release Candidate'. (see http://stackoverflow.com/questions/64602/what-are-differences-between-assemblyversion-assemblyfileversion-and-assemblyin)
Sample Code, Applications, and Programmer Documentation
- Every assembly should have a short (paragraph) relatively static description on the CodePlex wiki.
- All libraries and functions should have well documented sample code on the CodePlex web site.
- A few small sample applications will be built that can be downloaded and explored as a means to study the API.
- Internal code should be documented with the /// comment notation.
- When you commit code to DotSpatial you are transferring your copyright of that code to the DotSpatial project copyright holders.