Changes between Version 8 and Version 9 of MapGuideCodingStandards

Timestamp:

Jul 14, 2008, 11:21:07 AM (16 years ago)

Author:

jbirch

Comment:

work-saving commit...

MapGuideCodingStandards

@@ -198 +198 @@
 }}}
 
-
+== IDE Settings ==
+
+It is recommended that you use Visual Studio .NET for software development on Windwos and it helps if some settings are the same for all users.  Here are the ones you should make sure are set.
+
+Under Tools/Options/Text Editor/All Languages/Tabs, make sure the tab size is set to 4 and that the ‘Insert spaces’ option is turned on.  The use of spaces everywhere rather than a mix of tabs and spaces has the following advantages:
+
+ 1. It reduces the number of non-essential differences that show up when comparing files
+   * If I have my editor settings set to use spaces and I edit an area that contains tabs, Visual Studio will sometimes replace the tabs with spaces
+ 1. It prevents columns from lining up evenly
+   * File comparison tools may treat the width of tabs & spaces unevenly (1 tab does not exactly equal 4 spaces)
+   * Viewing a source file in Notepad is even worse: a tab is the equivalent of about 8 spaces
+
+== Stylistic Guidelines ==
+
+=== General ===
+
+Use the next-line convention for curly braces:
+{{{
+#!cpp
+public void Foo()
+{
+}
+}}}
+
+Another coding standard for C# is to preface all references to instance variables/properties/methods with the “this” keyword.  For example:
+{{{
+#!cpp
+public void Foo()
+{
+    // update an instance member variable
+    this.index = 0;
+
+    // call an instance member function
+    this.Foo();
+}
+}}}
+
+From a stylistic viewpoint, this makes it very easy to distinguish which variables are member variables and which have temporary scope.  In C++ this is typically done by prefixing names of member variables using “m_” and therefore the keyword “this” is not required.  
+
+All static variables are named using Pascal casing according to the .NET standard.  When referencing static constants or methods, always prefix it using the actual name of the class defining the constant or static method.  For example:
+{{{
+#!cpp
+public class MgFoo1
+{
+    /// <summary>
+    /// The max iterations to use.
+    /// </summary>
+    public int maxIter;
+
+    /// <summary>
+    /// Default value for max iterations.
+    /// </summary>
+    static public int defaultMaxIterations = 10;
+
+    ...
+}
+
+public class MgFoo2 extends MgFoo1
+{
+    ...
+
+    this.maxIter = this.defaultMaxIterations;  // wrong – not an instance variable
+    this.maxIter = MgFoo2.defaultMaxIterations;  // wrong - subclass doesn't declare it
+    this.maxIter = MgFoo1.defaultMaxIterations;  // correct
+
+    ...
+}
+}}}
+
+=== Compiler Warning ===
+
+This guideline strongly encourages all compiler warnings to be treated as errors and therefore they should be fixed.
+
+=== Strings ===
+
+==== Internally ====
+
+For the !MapGuide project the internal string format to use will be wstring. For .NET development the String class will be used.
+
+==== Across Wire ====
+
+The UTF-8 standard will be used for transmitting strings across the wire between any of the !MapGuide products (client, web tier, and server).
+
+==== Repository ====
+
+The resource repository used by MapGuide will use the UTF-8 standard for storing strings.
+
+==== API Boundary ====
+
+!MapGuide will use the following string format for API boundaries in the web tier and the server:
+{{{
+!#cpp
+const wstring&
+}}}
+
+=== Break and Goto ===
+
+Goto and break make the code very hard to read. I cannot believe that C# supports goto!!!
+The guideline is to avoid using break statements inside loops and to forbid the use of goto. 
+
+=== If, Else-If, Else Statements ===
+
+The if-else statements should have the following form: 
+{{{
+!#cpp
+if (condition) 
+{
+    statements;
+}
+
+if (condition) 
+{
+    statements;
+} 
+else 
+{
+    statements;
+}
+
+if (condition) 
+{
+    statements;
+} 
+else if (condition) 
+{
+    statements;
+} 
+else 
+{
+    statements;
+}
+}}}
+
+=== For Statements ===
+
+A for statement should have the following form: 
+{{{
+#!cpp
+for (initialization; condition; update) 
+{
+    statements;
+}
+}}}
+
+An empty for statement 
+{{{
+#!cpp
+        for (initialization; condition; update);
+}}}
+
+Variable declaration inside for statement should NOT be done.
+
+Don’t do this:
+{{{
+#!cpp
+for (int i=0; i<10; i++) 
+{
+    statements;
+}
+}}}
+
+Do this instead:
+{{{
+#!cpp
+int i=0;
+for (i=0; i<10; i++) 
+{
+    statements;
+}
+}}}
+
+