Changes between Version 43 and Version 44 of MapGuideCodingStandards

Timestamp:

09/19/22 05:56:31 (2 years ago)

Author:

jng

Comment:

More localization and C++11 notes

MapGuideCodingStandards

@@ -6 +6 @@
 
 ||'''Revision'''||'''Date'''||'''Author'''||'''Comment'''||
-||1.6.4||19 Sep, 2022||Jackie Ng||Clarified expected C++ standards level and added some considerations on public API naming/design||
+||1.6.4||19 Sep, 2022||Jackie Ng||Clarified expected C++ standards level, added some considerations on public API naming/design and more notes||
 ||1.6.3||26 Jan, 2015||Jackie Ng||Added section about argument checking||
 ||1.6.2||9 Dec, 2012||Jackie Ng||More about C++ documentation||
@@ -687 +687 @@
 }
 }}}
+
+=== C++11 language constructs ===
+
+As C++11 is the base language standard that the MapGuide/FDO codebase is expected to be compiled in, you are actively encouraged to take advantage of any language features/constructs introduced with this particular version of C++.
+
+As MapGuide/FDO was originally conceived before the introduction of C++11, there will be vast places in the codebase where code is written in the pre-C++11 style. You are encouraged (but not required) to migrate such existing code to the C++11 style if you encounter/touch it in your journey of fixing a bug or implementing a new feature. 2 key constructs C++11 constructs worthy of special consideration are detailed below
+
+==== `auto` ====
+
+Use `auto` where possible to let the C++ compiler infer the type of a local variable based on the type of the right-hand side of a variable assignment. This is most useful when dealing with STL iterators or sufficiently complex templated type where you can avoid having to specify the type like this:
+
+{{{
+std::vector<int>::iterator it = some_int_vector.begin();
+}}}
+
+and just declare it like this:
+
+{{{
+auto it = some_int_vector.begin();
+}}}
+
+`auto` also has useful applications for primitive variable declarations as it can fix up to one half of any potential `data type mismatch` warnings as a result of declaring the variable with an incorrect (or insufficiently wide) type on the left-hand side of a variable assignment (think `size_t`/`int` indexing mismatches in for loops for an example)
+
+However, do not use `auto` as the return type (aka. return type deduction) in any public API method signature. We need to be as verbose and concise as possible for SWIG to generate the correct proxy classes.
+
+==== for loops ====
+
+When working with STL iterators it is much more preferred to use the simplified range-based for loops introduced in C++11
+
+Pre C++11 loops look like this:
+
+{{{
+for (some_type::iterator it = container.begin(); it != container.end(); it++)
+{
+   some_item_type item = *it;
+   ...
+}
+}}}
+
+Such loops can be simplified to this:
+
+{{{
+for (auto const & item : container)
+{
+    ...
+}
+}}}
+
+With adjustments to whether the item needs to be `const` or by reference depending on the mutability needs of the iterated item.
 
 == Pointers ==
@@ -958 +1007 @@
 === C++ ===
 
-All strings which need to be localized must be placed into res resource files. 
+All strings which need to be localized must be placed into res resource files. The main string bundle resides in `Common/MapGuideCommon/Resources/mapguide_en.res`
 
 === General ===
 
-Strings which do not need to be localized can remain in the code.  However, you should indicate the string is non-localizable by adding a NOXLATE comment, e.g.
+Strings which do not need to be localized can remain in the code.  However, you should indicate the string is non-localizable by adding a `NOXLATE` comment, e.g.
 {{{
 #!cpp
@@ -971 +1020 @@
 }}}
 
-The comment indicates that the author of the code explicitly wants to exclude the string from being localized.
+The comment indicates that the author of the code explicitly wants to exclude the string from being localized and also facilitates detection of un-localized strings. Any matches for string literal searches without the instance of the `NOXLATE` comment on that line is a strong hint that such a string is meant to be localized.
 
 Exception string messages should be globalized if possible.
 
+Debugging/debug-only messages do not require localization and is assumed to be in English.
+
 == Special Comments ==