Changes between Version 36 and Version 37 of MapGuideCodingStandards

Timestamp:

09/19/22 04:35:29 (2 years ago)

Author:

jng

Comment:

Update pointer usage example to use unique_ptr and added some notes about public API design considerations

MapGuideCodingStandards

@@ -142 +142 @@
 
 Many times copy and paste is an easy way to make code work.  The downside is that it inflates the code and there is a risk of obfuscating essential details.  If some code is doing the same thing it's worthwhile trying to extract a helper method so that it can be reused.  This makes the code much easier to read and understand.  In the extreme case copy 'n paste leads to hundreds of lines of identical code with just a few lines of changes inside.  This significantly increases the risk of introducing defects, since when anything changes later in time the code has to be changed in many places instead of one.
+
+== Public API design considerations ==
+
+We use [https://swig.org/ SWIG] to generate wrappers to MapGuide's C++ public API surface in PHP, Java and .net.
+
+When introducing a new API to MapGuide, you should use the least-common-denominator subset of C++ language features/constructs to best facilitate wrapper generation across all 3 managed language targets, **even if this is not the most optimal method** in terms of C++ runtime performance.
+
+The following should be used for method parameters and return types:
+
+ * Allowed method parameter types
+   * Basic primitive types `bool/BYTE/INT16/INT32/INT64/float/double`
+   * Raw pointer to any public MapGuide API class
+   * For strings, only `std::wstring` (aliased in MapGuide as `STRING`) is permitted and only by const reference (aliased in MapGuide as `CREFSTRING`)
+   * For arrays/collections, use a raw pointer to any subclass of `MgCollection`
+   * For byte buffers or binary content, use a raw pointer to `MgByteReader`
+ * Allowed method return types
+   * Basic primitive types `bool/BYTE/INT16/INT32/INT64/float/double`
+   * Raw pointer to any public MapGuide API class
+   * For strings, only `std::wstring` (aliased in MapGuide as `STRING`) is permitted and only by value
+   * For byte buffers or binary content, return a raw pointer to `MgByteReader`
+
+Do not bother/try making public API methods `const`-correct, it will not affect SWIG interface generation and may even complicate or break it in some cases.
+
+Anything not on the above list is something assumed to not be reliably SWIG-wrappable with consistent behavior across our 3 managed language targets and should not be used.
+
+When naming methods, use a name that is unlikely to collide with reserved/built-in method names of any language target or methods that would be auto-generated by SWIG for given language target. For example:
+ * `delete` is a bad name for a new public API method because this is the name of the method SWIG auto-generates for Java proxy classes
+ * `finalize` is a bad name for a new public API method because this is the name of the built-in method in Java classes that will be called when an object is about to be garbage collected
+
+For private/internal methods, you are free to name and define method parameters and return type in any way you see fit for best C++ runtime performance.
 
 == Object Creation and Runtime Speed ==
@@ -684 +714 @@
 Bar* Foo::CreateBar()
 {
-    auto_ptr<Bar> bar;
+    unique_ptr<Bar> bar;
 
     MG_TRY()
 
-    bar = auto_ptr<Bar>(new Bar);
+    bar = unique_ptr<Bar>(new Bar);
     assert(0 != bar.get());
     bar.DoSomething(); // might throw an exception
@@ -697 +727 @@
 }
 }}}
- 
-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.
+
+Some smart pointer notes:
+
+ 1. Don't use `auto_ptr`. This is deprecated in C++11 and removed in C++17 onwards. Most/all cases where you'd think to use `auto_ptr` you can use `unique_ptr` instead
+ 2. If using `unique_ptr`, you may be tempted to use `std::make_unique`, but this is a C++14 standard library feature and we require code to be compiled in C++11 standards mode. If/when MapGuide/FDO adopts C++14 or higher as the base language standard version, usage of this API will be permitted.
+
 
 The following code is a cleaned up version of the above sample code using some helper macros.