[docs] Add a note on iteration of unordered containers to coding standards

[mgrang]

Summary

Beware of non-determinism due to iteration order of pointers

[mgrang]

Made changes in the text based on comments:

@dblaikie: "Might be worth pivoting this a bit differently to talk about ordering of pointers if that's the specific niche we're going to discourage/outlaw. (this could happen on std::set/map/etc too, when used with pointer keys)

Also "sort before iteration" is a bit too strong since it's only about when iterating to produce an ordered result (if it's an iteration to compute, say, a total or some order-agnostic summary/result, that's fine)."

docs/CodingStandards.rst

814

Thanks for the suggestions @dblaikie. How does this sound?

[dblaikie]

Sure, good enough for me.

I'd probably drop "iteration" from the title (maybe "Beware of non-determinism due to ordering of pointers" ?).

& maybe in the last sentence "like vector/MapVector/SetVector".

[mgrang]

Addressed comments.

docs/CodingStandards.rst

.. code-block:: c++
 
   // Remove the reference if you really want a new copy.
   for (auto Val : Container) { Val.change(); saveSomewhere(Val); }
 
   // Copy pointers, but make it clear that they're pointers.
   for (const auto *Ptr : Container) { observe(*Ptr); }
   for (auto *Ptr : Container) { Ptr->change(); }
 
+Beware of non-determinism due to iteration order of pointers
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+In general, there is no relative ordering among pointers. As a result,
+when unordered containers like sets and maps are used with pointer keys
+the iteration order is undefined. Hence, iterating such containers may
+result in non-deterministic code generation. While the generated code
+might not necessarily be "wrong code", this non-determinism might result
+in unexpected runtime crashes or simply hard to reproduce bugs on the
+customer side making it harder to debug and fix.
+
+As a rule of thumb, in case an ordered result is expected, remember to
+sort an unordered container before iteration. Or use an ordered
+container like vector if you want to iterate pointer keys.
+
 Style Issues
 ============
 
 The High-Level Issues
 ---------------------
 
 A Public Header File **is** a Module
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^