= !MapGuide Coding Standards =

This document was originally based on a document maintained by Bruce Deschant, entitled !MapGuide Coding Standards and Guidelines, rev 1.6, last updated July 7, 2008.

'''Revision History'''

||'''Revision'''||'''Date'''||'''Author'''||'''Comment'''||
||1.6||July 7, 2008||Bruce Deschant||Initial public revision||

[[PageOutline(2-4,Table of Contents,inline)]]

== Introduction ==

This document describes the coding guidelines to be used for the !MapGuide project. Here are a few reasons why we need coding guidelines:
 * Most of the cost of software goes to maintenance
 * The maintenance is done by many different individuals over the lifetime of a given software product and not the original developer.
 * Guidelines improve readability of the software and help make the learning curve of new developers easier.

== Consistency with .NET ==

Parts of !MapGuide will be based on Microsoft's .NET framework, and therefore we should understand and follow the standards/design guidelines recommended by Microsoft for .NET.  In Visual Studio .NET, you can find these under Design Guidelines for Class Library Developers.  Alternatively, you can go to the help index and navigate to:

{{{

   Visual Studio .NET
      .NET Framework
         Reference
            Design Guidelines for Class Library Developers

}}}

The guidelines discuss topics such as naming conventions, how to decide whether something should be a property or method, proper use of enumerations, delegates, and events, and lots of other things.  You should become generally familiar with these guidelines.

== Class Names ==

All class names should be prefixed with “Mg”.

Examples:

{{{
#!cpp
class MgServerSelectFeatures
class MG_SERVER_MAPPING_API MgMappingUtil
class MG_SERVER_RENDERING_API MgServerRenderingService : public MgRenderingService
}}}

== Class Variables ==

Any variable that needs to be visible outside of a class will expose itself via accessors (either protected, public, or internal).  In general we only use private member variables unless there is a very good reason for any other type.  Consequently, variables may be accessed directly only inside the class where they are defined.  All other access is done through the accessor.  This will help to support multi-threading and distributed objects.

== Documentation Standard ==

=== .NET/C++ ===

When you define a new public class, property, or method, you must follow the XML Doc standard.  Typing three slashes “///” just before a class/property/method declaration will bring up a skeleton XML Doc header in .NET, for C++ you will have to enter this.  You then simply need to add information in the different fields.  Note that if you fail to add the XML Doc header for .NET, the code may not compile (this is an option that we will enable for all our projects).

XML Doc Standard example:
{{{
#!cpp
///<summary>
///Summary of CanIgnoreElement.
///</summary>
///<remarks>
/// 
///</remarks>
///<param name="element">
///Description of parameter element
///</param>
///<param name="sFileName">
///Description of parameter sFileName
///</param>
/// <returns></returns> 
private bool CanIgnoreElement(Element element, string sFileName)
}}}

=== General ===

It’s important to stay disciplined to avoid getting into the habit of "coding now, documenting later".  Whenever you add or modify any classes/properties/methods, you must provide/update the documentation as well.  The documentation you write needs to be of sufficient quality so that someone other then you can work with it.  We as developers are ultimately responsible for providing the technical information that is required to fully document a class/property/method – not someone else.  We’ll refer to this documentation as "seed documentation", and its content should be as close as possible to the end-user reference documentation.

Note that private variables/properties/methods should be documented as well (for code readability).  In this case, however, simply use the normal C++ comment style, e.g.
{{{
#!cpp
// the shoe size, including half-sizes
private float shoeSize
}}}

== Object Creation and Runtime Speed ==

As with Java, unnecessary object creation is something you should avoid whenever possible.  Just be smart about it when you code.  For example, if a call to a method returns a new object and you call that method multiple times in the same context, then change your code to call this method only once and reuse the returned value.  Another example: use private helper objects when it makes sense to avoid unnecessary object creation. 

== Threading Guidelines ==

It’s important to follow strict threading rules when writing new code. Some of the MapGuide code will be used in a multithreaded deployment environment. Failing to follow multi-threading guidelines will be costly in the future. There are detailed guidelines provided by Microsoft's ''Design Guidelines for Class Library Developers'' ([ms-help://MS.VSCC/MS.MSDNVS/cpgenref/html/cpconnetframeworkdesignguidelines.htm local VS link]) that should be reviewed. 

Here are some points from those guidelines:

 * Avoid providing static methods that alter static state
 * Be aware of method calls in locked sections
 * Avoid the need for synchronization if possible
 * Avoid using global variables

== Source File Naming ==

The naming of source code files will match the class names except that the “Mg” prefix will be dropped.  For example, if I have a class called !MgClassA then all source files for that class will have the name !ClassA.  If this class is defined in C#, then there is only one source file with the .cs extension.  If this class is defined in C++, then there are two files: the source file with extension .cpp and the header file with extension .h.  No mismatches between class names and file names are allowed!

One consequence of this rule is that you can only define one class/enumeration/struct/interface per file.