Changes between Initial Version and Version 1 of MapGuideCodingStandards

Timestamp:

Jul 14, 2008, 10:53:13 AM (16 years ago)

Author:

jbirch

Comment:

Partial progress on coding standards wikification. Don't want to lose work...

MapGuideCodingStandards

@@ +1 @@
+= !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(3,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 ==
+
+=== 5.1 .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
+}}}
+