Changes between Version 7 and Version 8 of MapGuideCodingStandards

Timestamp:

Jul 14, 2008, 11:09:35 AM (16 years ago)

Author:

jbirch

Comment:

Formatting

MapGuideCodingStandards

@@ -91 +91 @@
 == 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. 
+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:
@@ -102 +102 @@
 == 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!
+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.
 
+== Folder Hierarchy ==
+
+Just as the file name reflects the class name, the folder hierarchy will reflect the namespace or module hierarchy.  If MgClassA is defined in the namespace OSGeo.!MapGuide.!DataAccess, then relative to the project root all source files for MgClassA will reside in the OSGeo\!MapGuide\!DataAccess folder.  You will see this hierarchy reflected in the source control application.  Again, having the hierarchies match up makes it very easy to navigate to where you want to go.
+
+A consequence of this rule is that if you change a namespace or module then you will also have to rename or restructure the file hierarchy.
+
+== Deleting Files and Projects ==
+
+Eventually everyone needs to remove files and/or projects from the main source.  If you’re removing files, you update the Visual Studio solution file and if applicable the Linux build script.  Having done this, you still need to remove the file / project from the source control application.
+
+== General Structure of !MapGuide Files
+
+We would like all !MapGuide files to have a similar structure:
+
+ 1. Copyright info
+   * every source file must have this at the top
+   * the actual text in the copyright is subject to change, but that doesn’t mean we shouldn’t add it
+   * whenever you create a new file, find another file with the copyright and paste that into your new file
+ 1. Import of .NET namespaces (If applicable)
+   * ideally sorted alphabetically
+ 1. Import of local namespaces (If applicable)
+   * ideally sorted alphabetically
+ 1. Namespace info (If applicable)
+   * as mentioned above, the namespace matches the folder path of the source file(s)
+ 1. Class declaration
+   * includes seed documentation
+ 1. Constant declarations 
+ 1. Local variable declarations
+ 1. Inner classes separated by section comments (If applicable)
+ 1. Constructors
+ 1. Properties/methods
+
+ 
+For example:
+{{{
+#!cpp
+//
+//  Copyright (C) 2004-2008 by Autodesk, Inc.
+//
+//  This library is free software; you can redistribute it and/or
+//  modify it under the terms of version 2.1 of the GNU Lesser
+//  General Public License as published by the Free Software Foundation.
+//
+//  This library is distributed in the hope that it will be useful,
+//  but WITHOUT ANY WARRANTY; without even the implied warranty of
+//  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+//  Lesser General Public License for more details.
+//
+//  You should have received a copy of the GNU Lesser General Public
+//  License along with this library; if not, write to the Free Software
+//  Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
+//
+
+using System;
+using System.Runtime.Serialization;
+
+namespace OSGeo.MapGuide.DataAccess.Tools
+{
+    /// <summary>
+    /// Provides the base functionality for ...
+    /// </summary>
+    [Serializable]
+    public class MyClass : ISerializable
+    {
+        //-------------------------------------------------------
+        // Constants
+        //-------------------------------------------------------
+        Constants
+
+        //-------------------------------------------------------
+        // Variables
+        //-------------------------------------------------------
+        Variables
+
+        //-------------------------------------------------------
+        // Inner classes
+        //-------------------------------------------------------
+        Inner classes
+
+        //-------------------------------------------------------
+        // Constructors
+        //-------------------------------------------------------
+        Constructors
+
+        //-------------------------------------------------------
+        // Properties / Methods
+        //-------------------------------------------------------
+        Properties / Methods
+    }
+}
+}}}
+
+