Changes between Version 11 and Version 12 of MapGuideCodingStandards

Timestamp:

Jul 14, 2008, 11:41:42 AM (16 years ago)

Author:

jbirch

Comment:

checkpoint

MapGuideCodingStandards

@@ -369 +369 @@
 }}}
 
-=== ForEach Statements ===
+=== !ForEach Statements ===
 
 A foreach statement should have the following form: 
@@ -523 +523 @@
 }}}
 
+== Pointers ==
+
+=== Normal Pointers ===
+
+A pointer should always be checked before using. You should never assume that the pointer will be valid.
+This is a good coding style and should be done.
+{{{
+#!cpp
+if (pData != NULL)
+{
+        int nSize = pData->GetSize();
+        ...
+}
+}}}
+
+This is a bad coding style and should not be done.
+{{{
+#!cpp
+int nSize = pData->GetSize();
+}}}
+
+When you are no longer using a pointer you should set it to NULL so that it is clear that it is no longer valid.
+{{{
+#!cpp
+...
+delete pData;
+pData = NULL;
+}}}
+
+=== Smart Pointers ===
+
+==== Our Code ====
+
+The !MapGuide Ptr template class acts as a smart pointer and should be used whenever possible.
+Example:
+{{{
+#!cpp
+MgRepository* MgServerResourceService::CreateRepository(CREFSTRING repositoryType, CREFSTRING repositoryName)
+{
+    Ptr<MgRepository> repository = 0;
+
+    MG_RESOURCE_SERVICE_TRY()
+
+    MgResourceServiceUtil::CheckArgument(!repositoryName.empty());
+
+    if (MgRepositoryType::Library == repositoryType)
+    {
+        repository = new MgLibraryRepository(repositoryName, this);
+    }
+    else if (MgRepositoryType::Session == repositoryType)
+    {
+        repository = new MgSessionRepository(repositoryName, this);
+    }
+    else
+    {
+        throw new MgInvalidRepositoryTypeException(__FILE__, __LINE__);
+    }
+
+    MgResourceServiceUtil::CheckMemory(repository);
+
+    MG_RESOURCE_SERVICE_CATCH_AND_THROW()
+
+    assert(0 == mgException);
+
+    (*repository).AddRef();     // Ownership is transferred to the caller
+
+    return repository;
+}
+}}}
+
+==== 3rd Party Library ====
+
+Wherever possible the standard C++ smart pointer should be used when dealing with 3rd party libraries.
+
+The following is some sample code that uses the standard C++ smart pointer along with a typical !MapGuide Exception handling mechanism:
+
+{{{
+#!cpp
+Bar* Foo::CreateBar()
+{
+    auto_ptr<Bar> bar;
+
+    MG_TRY()
+
+    bar = auto_ptr<Bar>(new Bar);
+    assert(0 != bar.get());
+    bar.DoSomething(); // might throw an exception
+
+    MG_CATCH_AND_THROW()
+
+    return bar.release(); // release ownership of the smart pointer
+}
+}}}
+ 
+Standard C++ smart pointer notes:
+ 1. Never use auto_ptr objects as elements of STL containers because auto_ptr does not quite meet the requirements of a type you can put into containers (i.e. copies of auto_ptrs are not equivalent).
+ 1. Never use an array as an auto_ptr argument because auto_ptr's destructor invokes only non-array delete.
+
+The following code is a cleaned up version of the above sample code using some helper macros.
+{{{
+#!cpp
+Bar* Foo::CreateBar()
+{
+    char* bar = 0;
+
+    MG_TRY()
+
+    bar = new char[256];
+    assert(0 != bar);
+    DoSomething(bar);
+
+    MG_CATCH()
+
+    if (0 != mgException)
+    {
+        delete[] bar;
+        throw mgException;
+    }
+
+    return bar;
+}
+}}}
+
+Note that MG_TRY(), MG_CATCH(), MG_THROW, MG_CATCH_AND_THROW and MG_CATCH_AND_RELEASE() macros can be anything specific to a !MapGuide component.
+ 
+Example macro definitions for the resource service:
+{{{
+#!cpp
+#define MG_RESOURCE_SERVICE_TRY()                                             \
+    MG_TRY()                                                                  \
+
+#define MG_RESOURCE_SERVICE_CATCH(methodName)                                 \
+    }                                                                         \
+    catch (XmlException& e)                                                   \
+    {                                                                         \
+        MgStringCollection arguments;                                         \
+        STRING message;                                                       \
+                                                                              \
+        if (DB_LOCK_DEADLOCK == e.getDbErrno())                               \
+        {                                                                     \
+            message = MgUtil::GetResourceMessage(                             \
+                MgResources::ResourceService, L"MgRepositoryBusy");           \
+        }                                                                     \
+        else                                                                  \
+        {                                                                     \
+            MgUtil::MultiByteToWideChar(string(e.what()), message);           \
+        }                                                                     \
+                                                                              \
+        arguments.Add(message);                                               \
+        mgException = new MgDbXmlException(methodName, __LINE__, __WFILE__, NULL, L"MgFormatInnerExceptionMessage", &arguments); \
+        (static_cast<MgThirdPartyException*>(mgException.p))->SetErrorCode(e.getDbErrno()); \
+    }                                                                         \
+    catch (DbException& e)                                                    \
+    {                                                                         \
+        MgStringCollection arguments;                                         \
+        STRING message;                                                       \
+                                                                              \
+        if (DB_LOCK_DEADLOCK == e.get_errno())                                \
+        {                                                                     \
+            message = MgUtil::GetResourceMessage(                             \
+                MgResources::ResourceService, L"MgRepositoryBusy");           \
+        }                                                                     \
+        else                                                                  \
+        {                                                                     \
+            MgUtil::MultiByteToWideChar(string(e.what()), message);           \
+        }                                                                     \
+                                                                              \
+        arguments.Add(message);                                               \
+        mgException = new MgDbException(methodName, __LINE__, __WFILE__, NULL, L"MgFormatInnerExceptionMessage", &arguments); \
+        (static_cast<MgThirdPartyException*>(mgException.p))->SetErrorCode(e.get_errno()); \
+    }                                                                         \
+    catch (DWFException& e)                                                   \
+    {                                                                         \
+        MgStringCollection arguments;                                         \
+        arguments.Add(STRING(e.message()));                                   \
+        mgException = new MgDwfException(methodName, __LINE__, __WFILE__, NULL, L"MgFormatInnerExceptionMessage", &arguments); \
+    }                                                                         \
+    catch (const XMLException& e)                                             \
+    {                                                                         \
+        MgStringCollection arguments;                                         \
+        arguments.Add(X2W(e.getMessage()));                                   \
+        mgException = new MgXmlParserException(methodName, __LINE__, __WFILE__, NULL, L"MgFormatInnerExceptionMessage", &arguments); \
+    }                                                                         \
+    catch (const DOMException& e)                                             \
+    {                                                                         \
+        MgStringCollection arguments;                                         \
+        arguments.Add(X2W(e.msg));                                            \
+        mgException = new MgXmlParserException(methodName, __LINE__, __WFILE__, NULL, L"MgFormatInnerExceptionMessage", &arguments); \
+                                                                              \
+    MG_CATCH(methodName)                                                      \
+
+#define MG_RESOURCE_SERVICE_THROW()                                           \
+    MG_THROW()                                                                \
+
+#define MG_RESOURCE_SERVICE_CATCH_AND_THROW(methodName)                       \
+    MG_RESOURCE_SERVICE_CATCH(methodName)                                     \
+                                                                              \
+    MG_RESOURCE_SERVICE_THROW()                                               \
+}}}
+
+== Enumerations ==
+
+Please use the following format when declaring enumerations.
+
+Example 1:
+{{{
+#!cpp
+enum MgDimensionality
+{
+    mdXY = 0,   /// XY
+    mdXYM,              /// XY + Measure
+    mdXYZ,              /// XYZ
+    mdXYZM,             /// XYZ + Measure
+};
+}}}
+
+Example 2:
+{{{
+#!cpp
+enum MgConnectionState
+{
+    mcsOpen = 0,   /// Connection is still open
+    mcsClose,      /// Connection has been closed
+    mcsBusy        /// Connection is busy processing other request
+};
+}}}
+
+You will notice that the 1st letter of each word is part of the enumeration value.
+Also, when using enumerations in your code ALWAYS do the following:
+{{{
+#!cpp
+ConnectionState::mcsOpen
+}}}
+Do NOT do the following:
+{{{
+#!cpp
+mcsOpen
+}}}
+
+== Parentheses ==
+
+Even if the operator precedence seems clear to you, it is best to use parentheses to avoid any confusion by others.
+{{{
+#!cpp
+if (a == b && c == d)     // Bad
+if ((a == b) && (c == d)) // Good
+}}}
+
+== Assert ==
+
+=== .NET ===
+
+Use Debug.Assert ( condition ) to do assertions. Do not use Trace.Assert as that will not be removed for release build.
+
+For C++ .NET projects you must do the following or else the Debug calls will still be called in release builds.
+{{{
+#!cpp
+#ifdef _DEBUG
+Debug::WriteLine(SrsErrorMessage(status));
+#endif    
+}}}
+
+
+
+