ChangeLogTag: Thu Aug 26 12:11:09 1999 David L. Levine <levine@cs.wustl.edu>

2 files changed, 41 insertions, 10 deletions

diff --git a/ChangeLog-99b b/ChangeLog-99b
index c33059f06ab..fc354e51d2e 100644
--- a/ChangeLog-99b
+++ b/ChangeLog-99b
@@ -1,3 +1,8 @@
+Thu Aug 26 12:11:09 1999  David L. Levine  <levine@cs.wustl.edu>
+
+        * docs/ACE-guidelines.html: added guidelines to avoid
+          default arguments, and favor narrow interfaces.
+
 Thu Aug 26 11:44:26 1999  David L. Levine  <levine@cs.wustl.edu>
 
         * tests/Time_Value_Test.cpp (main): added static casts
diff --git a/docs/ACE-guidelines.html b/docs/ACE-guidelines.html
index 9dd45d48385..1082c80a61f 100644
--- a/docs/ACE-guidelines.html
+++ b/docs/ACE-guidelines.html
@@ -86,6 +86,13 @@ bgcolor="#ffffff">
     <li>Avoid including the string ``Error'' in a source code filename.
         GNU Make's error messages start with ``Error''.  So, it's much
         easier to search for errors if filenames don't contain ``Error''.<p>
+
+    <li>Narrow interfaces are better than wide interfaces.  If there
+        isn't a need for an interface, leave it out.  This eases maintenance,
+        minimizes footprint, and reduces the likelihood of interference
+        when other interfaces need to be added later.  (See the
+        <a href="#ACE_Time_Value example">ACE_Time_Value example</a>
+        below.<p>
   </ul>
 
   <li><strong>Code Documentation</strong><p>
@@ -333,10 +340,9 @@ The correct way to write that guard is:
       defines a struct name <strong>exception</strong>, which complicates
       use of exceptions.<p>
 
-    <li>On a <CODE>.cpp</CODE> file always include the corresponding
-      header file <EM>first</EM>, like this:<P>
-
-<PRE>
+    <li>On a <code>.cpp</code> file always include the corresponding
+      header file <em>first</em>, like this:<p>
+<pre>
         // This is Foo.cpp
 
         #include "Foo.h"
@@ -344,20 +350,20 @@ The correct way to write that guard is:
         #include "ace/Baz.h"
 
         // Here comes the Foo.cpp code....
-</PRE><P>
+</pre><p>
 
       In this way we are sure that the header file is self-contained
       and can be safely included from some place else.
 
-    <li>In the TAO library <B>never</B> include
-      <CODE>&lt;corba.h&gt</CODE>, this file should only be included
+    <li>In the TAO library <strong>never</strong> include
+      <code>&lt;corba.h&gt</code>, this file should only be included
       by the user and introduces cyclic dependencies in the library
       that we must avoid.<p>
 
     <li>Never include a header file when a forward reference will do,
       remember that templates can be forward referenced too.
       Consult your favorite C++ book to find out when you must include 
-      the full class definition.<P>
+      the full class definition.<p>
   </ul>
 
   <li><strong>C++ Syntax and Constructs</strong><p>
@@ -550,6 +556,26 @@ Foo::bar ()
         for convenience, if its performance is not critical, it is usually
         easiest just to make the virtual destructor non-inline.)<p>
 
+    
+    <li><a name="ACE_Time_Value example">Avoid default arguments</a>
+        unless there's a good reason.  For an example of how they got
+        us into a jam is:
+        <pre>
+        ACE_Time_Value (long sec, long usec = 0);
+        </pre>
+
+        So, <code>ACE_Time_Value (2.5)</code> has the unfortunate
+        effect of coercing the 2.5 to a long with value 2.  That's
+        probably not what the programmer intended, and many compilers
+        don't warn about it.<p>
+
+        A nice fix would be to add an <code>ACE_Time_Value (double)</code>
+        constructor.  But, that would cause ambiguous overloading
+        due to the default value for the second argument of
+        <code>ACE_Time_Value (long sec, long usec = 0)</code>.
+        We're stuck with <code>ACE_Time_Value</code>, but now we
+        know that it's easy to avoid.<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
@@ -797,8 +823,8 @@ Foo::bar ()
         </table><p>
         Where:
 
-        <UL>
-          <LI>UNICODE: When <code>UNICODE</code> is defined.
+        <ul>
+          <li>UNICODE: When <code>UNICODE</code> is defined.
           <li>MOSTLY: When <code>ACE_HAS_MOSTLY_UNICODE_APIS</code> is
               defined
           <li>C: char *