added guidelines on constructor initializer ordering and ACE_LOG_MSG->op_status () in ctors

1 files changed, 28 insertions, 4 deletions

diff --git a/etc/ACE-guidelines.html b/etc/ACE-guidelines.html
index f41ca66a479..cb77b85bff2 100644
--- a/etc/ACE-guidelines.html
+++ b/etc/ACE-guidelines.html
@@ -97,7 +97,7 @@ to Graham for providing the OSE tools!<p>
   <ul>
     <li>Never #include standard headers directly, except in a few
         specific ACE files, <em>e.g.</em>, OS.h and stdcpp.h.  Let
-        those files #include the correct headers.  If you don't do
+        those files #include the correct headers.  If you do not do
         this, your code will not compile with the Standard C++ Library.<p>
 
     <li>Always follow a preprocessor <strong><code>#endif</code></strong>
@@ -231,7 +231,31 @@ to Graham for providing the OSE tools!<p>
         certain size, <em>e.g.</em>, 4 bytes.  <strong>long</strong> is
         not 4 bytes on all platforms; it is 8 bytes on many 64-bit
         machines.  ACE_UINT32 is always 4 bytes, and ACE_hrtime_t is
-        always 8 bytes.  (We should/may/will add an ACE_UINT64, soon.)
+        always 8 bytes.  (We should/may/will add an ACE_UINT64, soon.)<p>
+
+   <li>Constructor initializers must appear in the same order as
+       the data members are declared in the class header.  This avoids
+       subtle errors, because initialization takes place in the order
+       of member declaration.<p>
+
+   <li>Because ACE does not use exception handling, dealing with
+       failures requires a bit of care.  This is especially true
+       in constructors.  Consider the following approach:
+
+       <pre>
+       ACE_NEW_RETURN (this-&gt;name_space_, LOCAL_NAME_SPACE, -1);
+
+       if (ACE_LOG_MSG-&gt;op_status () != 0)
+       ....
+       </pre>
+
+       This snip of code is from
+       <a href="../ace/Naming_Context.cpp"><code>ACE_Naming_Context</code></a>.
+       All failed constructors in ACE (should) call ACE_ERROR.  This sets
+       the thread specific <strong>op_status</strong>, which can be checked
+       by the caller.  This mechanism allows the caller to check for a failed
+       constructor without the requiring the constructor to throw
+       exceptions.<p>
   </ul>
 
   <li><strong>I/O</strong><p>
@@ -282,8 +306,8 @@ to Graham for providing the OSE tools!<p>
   <li>Do not use exception handling.  Some platforms do not support it.
       And, it imposes an execution speed penalty.<p>
 
-  <li>Avoid using STL in our applications.  Some platforms do not
-      support it yet.<p>
+  <li>Avoid using the C++ Standard Template Library (STL) in our
+      applications.  Some platforms do not support it yet.<p>
 </ul><p>
 
 <h3><a href="http://www.cs.wustl.edu/~levine/CVS.html">ACE</a>