ACE/docs/ACE-guidelines.html

   1 <!--  -->
   2
   3 <html>
   4   <head>
   5     <title>ACE Software Development Guidelines</title>
   6     <link rev=made href="https://github.com/DOCGroup/ACE_TAO">
   7   </head>
   8
   9 <body text = "#000000"
  10 link="#000fff"
  11 vlink="#ff0f0f"
  12 bgcolor="#ffffff">
  13
  14 <hr>
  15 <h3>ACE Software Development Guidelines</h3>
  16
  17 <ul>
  18   <li><strong>General</strong><p>
  19   <ul>
  20     <li>Every text file must end with a newline.<p>
  21
  22     <li>Use spaces instead of tabs, except in Makefiles.  Emacs users
  23         can add this to their <strong>.emacs</strong>:
  24
  25         <pre>(setq-default indent-tabs-mode nil)</pre></p>
  26
  27         Microsoft Visual C++ users should do the following:
  28
  29         <pre>
  30         Choose:  Tools -- Options -- Tabs
  31         Then Set:  "Tab size" to 8 and "Indent size" to 2, and
  32         indent using spaces.
  33         </pre><p>
  34
  35     <li>Do not end text lines with spaces.  Emacs users can add this to
  36         their <strong>.emacs</strong>:
  37
  38         <pre>(setq-default nuke-trailing-whitespace-p t)</pre>
  39
  40         Newer versions of emacs will require the following instead:
  41
  42         <pre>(add-hook 'before-save-hook 'delete-trailing-whitespace)</pre>
  43
  44         <strong>Note for Microsoft Visual Studio .NET Users:</strong>
  45         <p>There is a macro project <code>(ace_guidelines.vsmacros)</code>
  46         located in <code>$ACE_ROOT/docs</code> that replaces tabs with spaces
  47         and removes trailing spaces each time you save a file.</p>
  48
  49     <li>Try to limit the length of source code lines to less than 80
  50         characters.  Users with 14 inch monitors appreciate it when
  51         reading code.  And, it avoids mangling problems with email
  52         and net news.<p>
  53
  54         <li>Try to avoid creating files with excessively long names (45 characters).
  55         Moreover, ensure that the names of generated files e.g. <code>MakeProjectCreator</code>,
  56         <code>tao_idl</code> do not also go beyond that limit. Some operating
  57         systems cannot handle very long file names correctly.<p>
  58
  59     <li>If you add a comment to code that is directed to, or
  60         requires the attention of, a particular individual:
  61         <strong>SEND EMAIL TO THAT INDIVIDUAL!</strong>.<p>
  62
  63     <li>Every program should have a "usage" message.  It should be
  64         printed out if erroneous command line arguments, or a
  65         <strong><code>-?</code></strong> command line argument, are
  66         provided to the program.<p>
  67
  68     <li>An ACE-using program's entry point should use the portable form:
  69         <pre>
  70         int ACE_TMAIN (int argc, ACE_TCHAR *argv[])
  71         </pre>
  72         This form is portable to all ACE platforms whether using narrow
  73         or wide characters. The other two common forms:
  74         <pre>
  75         int main (int argc, char *argv[])
  76         int wmain (int argc, wchar_t *argv[])
  77         </pre>
  78         as well as any other main entrypoint form should only be used
  79         when there is some overarching reason to not use the portable form.
  80         One example would be a Windows GUI program that requires WinMain.
  81         <p>See <a href="wchar.txt"><code>$ACE_ROOT/docs/wchar.txt</code></a>
  82         for more information on ACE support on <code>wchar</code>.<p>
  83
  84     <li>The program entry point function, in any form mentioned above, must
  85         always be declared with arguments, <em>e.g.</em>,
  86         <pre>
  87         int
  88         ACE_TMAIN (int argc, ACE_TCHAR *argv[])
  89         {
  90           [...]
  91
  92           return 0;
  93         }
  94         </pre><p>
  95
  96         If you don't use the <code>argc</code> and/or <code>argv</code>
  97         arguments, don't declare them, <em>e.g.</em>,
  98         <pre>
  99         int
 100         ACE_TMAIN (int, ACE_TCHAR *[])
 101         {
 102           [...]
 103
 104           return 0;
 105         }
 106         </pre><p>
 107
 108         Please declare the second argument as <code>ACE_TCHAR *[]</code>
 109         instead of <code>ACE_TCHAR **</code> or <code>char *[]</CODE>.
 110         Ancient versions of MSC++
 111         complained about <code>ACE_TCHAR **</code> and <code>char
 112         *[]</CODE> is not Unicode-compliant.<p>
 113
 114         <code>main</code> must also return 0 on successful
 115         termination, and non-zero otherwise.<p>
 116
 117     <li>Avoid including the string "<code>Error</code>" in a source
 118             code filename. GNU Make's error messages start with
 119             "<code>Error</code>".  So, it's much easier to search for
 120             errors if filenames don't contain "<code>Error</code>".<p>
 121
 122
 123     <li>Narrow interfaces are better than wide interfaces.  If there
 124         isn't a need for an interface, leave it out.  This eases maintenance,
 125         minimizes footprint, and reduces the likelihood of interference
 126         when other interfaces need to be added later.  (See the
 127         <a href="#ACE_Time_Value example">ACE_Time_Value</a> example
 128         .<p>
 129
 130      <li> Never use <CODE>assert()</CODE> macros or related constructs
 131          (such as abort()) calls in core ACE and TAO
 132          library/framework code.  These macros are a major problem for
 133          production software that uses this code since the
 134          error-handling strategy (i.e., abort the process) is
 135          excessive.  Instead, extract out the expressions from
 136          assert() macros and use them as
 137          precondition/postconditions/invariants in the
 138          software and return any violations of these
 139          conditions/invariants via exceptions or error return values.
 140          It's fine to use <CODE>assert()</CODE> macros et al. in test
 141          programs, but make sure these tests never find their way into
 142          the core ACE and TAO library/framework code base. <P>
 143
 144   </ul>
 145
 146   <li><strong>Coding Style</strong><p>
 147   <ul>
 148   <LI> When writing ACE and TAO class and method names make sure to use underscores ('_') to separate the parts of a name rather than intercaps.  For example, use
 149
 150         <pre>
 151         class ACE_Monitor_Control
 152         {
 153         public:
 154           int read_monitor ();
 155           // ...
 156         };
 157         </PRE>
 158
 159 rather than
 160
 161         <pre>
 162         class ACEMonitorControl
 163         {
 164         public:
 165           int readMonitor ();
 166           // ...
 167         };
 168         </PRE>
 169
 170   </UL>
 171
 172   <li><strong>Code Documentation</strong><p>
 173   <ul>
 174     <li>Use comments and whitespace (:-) liberally.  Comments
 175         should consist of complete sentences, <em>i.e.</em>, start
 176         with a capital letter and end with a period.<p>
 177
 178     <li>Be sure to follow the guidelines and restrictions for use of the
 179         documentation tools for ACE
 180         header files, which must follow the
 181         <a href="http://www.doxygen.org/">Doxygen</a>
 182         format requirements.
 183         The complete documentation for Doxygen is available in the
 184         <a href="http://www.stack.nl/~dimitri/doxygen/download.html#latestman">
 185         Doxygen manual</a>.
 186         For an example header file using Doxygen-style comments,
 187         please refer to <a href="../ace/ACE.h">ACE.h</a>.<p>
 188
 189     <li>The header file comment should at least contain the following
 190         entries:
 191         <pre>
 192         /**
 193          * @file Foo.h
 194          * @author Authors Name &lt;author@email.org&gt;
 195          *
 196          *  A few words describing the file.
 197          */
 198         </pre></p>
 199
 200     <li>A class should be commented this way:
 201         <pre>
 202         /**
 203          * @class Foo_Impl
 204          * @brief A brief description of the class
 205          *
 206          * A more detailed description.
 207          */
 208         </pre></p>
 209
 210      <li>The preferred way to document methods is:
 211          <pre>
 212          /// This function foos the bars
 213          /// another line of documentation if necessary
 214          /// @param bar The bar you want to foo
 215          void foo (int bar);
 216          </pre></p>
 217
 218     <li>All binary options for ACE and TAO should be specified in
 219         terms of the integral values 0 and 1, rather than "true" and
 220         "false" or "yes" and "no".  All TAO options should be
 221         documented in the <A HREF="../TAO/docs/Options.html">online
 222         TAO options document</A>. <P>.
 223
 224   </ul>
 225
 226   <li><strong>Preprocessor</strong><p>
 227   <ul>
 228     <li>Never #include standard headers directly, except in a few
 229         specific ACE files, <em>e.g.</em>, OS.h and stdcpp.h.  Let
 230         those files #include the correct headers.  If you do not do
 231         this, your code will not compile with the Standard C++ Library.<p>
 232
 233     <li>Always use <strong><code>#if defined (MACRONAME)</code></strong>
 234         to test if a macro is defined, rather than the simpler
 235         <strong><code>#if MACRONAME</code></strong>. Doxygen requires this.
 236         The one exception to this the macros used to prevent multiple
 237         inclusion of header files, as shown below.
 238
 239     <li>Always follow a preprocessor <strong><code>#endif</code></strong>
 240         with a <strong><code>/*  */</code></strong> C-style comment. Using
 241         C-style comments with preprocessor code is required for some old
 242         compilers. It should correspond to the condition in the matching
 243         <strong><code>#if</code></strong> directive.  For example,
 244         <pre>
 245         #if defined (ACE_HAS_THREADS)
 246         #  define ACE_SCOPE_PROCESS 0
 247         #  define ACE_SCOPE_LWP 1
 248         #  define ACE_SCOPE_THREAD 2
 249         #endif /* ACE_HAS_THREADS */
 250         </pre><p>
 251
 252     <li>Be sure to put spaces around comment delimiters, e.g.,
 253         <strong><code>char * /* foo */</code></strong> instead of
 254         <strong><code>char */*foo*/</code></strong>.  MS VC++
 255         complains otherwise.<p>
 256
 257     <li>Always insert a <strong><code>/**/</code></strong> between an
 258         <strong><code>#include</code></strong> and
 259         <strong><code>filename</code></strong>, for system headers and
 260         <strong><code>ace/pre.h</code></strong> and
 261         <strong><code>ace/post.h</code></strong> as
 262         shown in the above example.  This avoids dependency problems
 263         with Visual C++ and prevents Doxygen from including the
 264         headers in the file reference trees.  <p>
 265
 266     <li>Be very careful with names of macros, <code>enum</code> values, and variables
 267         It's always best to prefix them with something like <code>ACE_</code>
 268         or <code>TAO_</code>.  There are too many system headers out
 269         there that <code>#define</code> <code>OK</code>, <code>SUCCESS</code>,
 270         <code>ERROR</code>, <code>index</code>, <code>s_type</code>,
 271         and so on.<p>
 272
 273     <li>When using macros in an arithmetic expression, be sure to test
 274       that the macro is defined, using <code>defined(<em>macro</em>)</code> before specifying
 275       the expression.  For example:
 276 <pre>
 277 #if __FreeBSD__ &lt; 3
 278 </pre>
 279
 280 will evaluate true on any platform where <code>__FreeBSD__</code> is
 281 not defined.  The correct way to write that guard is:
 282 <pre>
 283 #if defined (__FreeBSD__)  &&  __FreeBSD__ &lt; 3
 284 </pre>
 285
 286 If using g++, problems like this can be flagged as a warning by using the "<code>-Wundef</code>" command line option.
 287
 288     <li>Try to centralize <code>#ifdef</code>s with <code>typedef</code>s
 289         and <code>#define</code>s.  For example, use this:
 290         <pre>
 291         #if defined(ACE_FOO)
 292           typedef long ACE_NETIF_TYPE;
 293         # define ACE_DEFAULT_NETIF 0
 294         #else  /* ! ACE_FOO */
 295           typedef const TCHAR* ACE_NETIF_TYPE;
 296         # define ACE_DEFAULT_NETIF ASYS_TEXT("le0")
 297         #endif /* ! ACE_FOO */
 298         </pre><p>
 299
 300         instead of:
 301
 302         <pre><p>
 303         #if defined (ACE_FOO)
 304           // Foo supports numbers, not names for network interfaces
 305           long net_if,
 306         #else  /* ! ACE_FOO */
 307           const TCHAR *net_if,
 308         #endif /* ! ACE_FOO */
 309         </pre><p>
 310
 311     <li>Protect header files against multiple inclusion with this
 312         construct:
 313         <pre>
 314         #ifndef FOO_H
 315         #define FOO_H
 316
 317         [contents of header file]
 318
 319         #endif /* FOO_H */
 320         </pre><p>
 321
 322         This exact construct (note the <code>#ifndef</code>)
 323         is optimized by many compilers such they only open the
 324         file once per compilation unit.  Thanks to Eric C. Newton
 325         &lt;ecn@smart.net&gt; for pointing that out.<p>
 326
 327         If the header <code>#include</code>s an ACE library header,
 328         then it's a good idea to include the <code>#pragma once</code>
 329         directive:
 330         <pre>
 331         #ifndef FOO_H
 332         #define FOO_H
 333
 334         #include "ace/ACE.h"
 335         #if !defined (ACE_LACKS_PRAGMA_ONCE)
 336         # pragma once
 337         #endif /* ACE_LACKS_PRAGMA_ONCE */
 338
 339         [contents of header file]
 340
 341         #endif /* FOO_H */
 342         </pre><p>
 343
 344         <code>#pragma once</code> must be protected, because some
 345         compilers complain about it.  The protection depends on
 346         <code>ACE_LACKS_PRAGMA_ONCE</code>, which is defined in
 347         some ACE config headers.  Therefore, the protected
 348         <code>#pragma once</code> construct should only be used after
 349         an <code>#include</code> of an ACE library header.  Note that
 350         many compilers enable the optimization if the <code>#ifndef</code>
 351         protection construct is used, so for them, <code>#pragma once</code>
 352         is superfluous.<p>
 353
 354         <strong>No</strong> code can appear after the final
 355         <code>#endif</code> for the optimization to be effective and
 356         correct.<p>
 357
 358     <li><p>Files that contain parametric classes should follow this style:
 359       <pre>
 360       #ifndef FOO_T_H
 361       #define FOO_T_H
 362
 363       #include "ace/ACE.h"
 364       #if !defined (ACE_LACKS_PRAGMA_ONCE)
 365       # pragma once
 366       #endif /* ACE_LACKS_PRAGMA_ONCE */
 367
 368       // Put your template declarations here...
 369
 370       #if defined (__ACE_INLINE__)
 371       #include "Foo_T.inl"
 372       #endif /* __ACE_INLINE__ */
 373
 374       #include "Foo_T.cpp"
 375
 376       #endif /* FOO_T_H */
 377 </pre></p>
 378       <p>
 379       Notice that some compilers need to see the code of the template,
 380       hence the <code>.cpp</code> file must be included from the
 381       header file.
 382       </p>
 383       <p>
 384       To avoid multiple inclusions of the <code>.cpp</code> file it
 385       should also be protected as in:
 386       <pre>
 387       #ifndef FOO_T_CPP
 388       #define FOO_T_CPP
 389
 390       #include "Foo_T.h"
 391       #if !defined (ACE_LACKS_PRAGMA_ONCE)
 392       # pragma once
 393       #endif /* ACE_LACKS_PRAGMA_ONCE */
 394
 395       #if !defined (__ACE_INLINE__)
 396       #include "ace/Foo_T.inl"
 397       #endif /* __ACE_INLINE__ */
 398
 399       // put your template code here
 400
 401       #endif /* FOO_T_H */
 402 </pre></p>
 403       <p>Finally, you may want to include the template header file from a
 404       non-template header file (check
 405       <code>$ACE_ROOT/ace/Synch.h</code>); in such a case the template
 406       header should be included <strong>after</strong> the inline
 407       function definitions, as in:</p>
 408       <p><pre>
 409       #ifndef FOO_H
 410       #define FOO_H
 411
 412       #include "ace/ACE.h"
 413       #if !defined (ACE_LACKS_PRAGMA_ONCE)
 414       # pragma once
 415       #endif /* ACE_LACKS_PRAGMA_ONCE */
 416
 417       // Put your non-template declarations here...
 418
 419       #if defined (__ACE_INLINE__)
 420       #include "Foo.inl"
 421       #endif /* __ACE_INLINE__ */
 422
 423       #include "Foo_T.h"
 424
 425       #endif /* FOO_H */
 426 </pre></p></li>
 427
 428     <li>Avoid <code>#include &lt;math.h&gt;</code> if at all possible.
 429       The <code>/usr/include/math.h</code> on SunOS 5.5.1 through 5.7
 430       defines a struct name <strong>exception</strong>, which complicates
 431       use of exceptions.<p>
 432
 433     <li>On a <code>.cpp</code> file always include the corresponding
 434       header file <em>first</em>, like this:<p>
 435 <pre>
 436         // This is Foo.cpp
 437
 438         #include "Foo.h"
 439         #include "tao/Bar.h"
 440         #include "ace/Baz.h"
 441
 442         // Here comes the Foo.cpp code....
 443 </pre><p>
 444
 445       In this way we are sure that the header file is self-contained
 446       and can be safely included from some place else.
 447
 448     <li>In the TAO library <strong>never</strong> include
 449       <code>&lt;corba.h&gt</code>, this file should only be included
 450       by the user and introduces cyclic dependencies in the library
 451       that we must avoid.<p>
 452
 453     <li>Never include a header file when a forward reference will do,
 454       remember that templates can be forward referenced too.
 455       Consult your favorite C++ book to find out when you must include
 456       the full class definition.<p>
 457   </ul>
 458
 459   <li><strong>C++ Syntax and Constructs</strong><p>
 460   <ul>
 461     <li><strong><code>for</code></strong> loops should look like:
 462         <pre>
 463         for (unsigned int i = 0; i &lt; count; ++i)
 464           ++total;
 465         </pre>
 466
 467         Similarly, <strong><code>if</code></strong> statements should have
 468         a space after the "<strong>if</strong>", and no spaces just after
 469         the opening parenthesis and just before the closing parenthesis.<p>
 470
 471         If there's just one statement in the loop or if statement
 472         there's no need to use additional braces.
 473
 474     <li>If a loop index is used after the body of the loop, it
 475         <strong>must</strong> be declared before the loop.  For example,
 476
 477         <pre>
 478         size_t i = 0;
 479         for (size_t j = 0; file_name [j] != '\0'; ++i, ++j)
 480           {
 481             if (file_name [j] == '\\' && file_name [j + 1] == '\\')
 482               ++j;
 483
 484             file_name [i] = file_name [j];
 485           }
 486
 487         // Terminate this string.
 488         file_name [i] = '\0';
 489         </pre><p>
 490
 491    <li>Prefix operators are generally more efficient than postfix
 492        operators.  Therefore, they are preferred over their postfix
 493        counterparts where the expression value is not used.<p>
 494
 495        Therefore, use this idiom for iterators, with prefix operator
 496        on the loop index:
 497        <pre>
 498        ACE_Ordered_MultiSet&lt;int&gt; set;
 499        ACE_Ordered_MultiSet_Iterator&lt;int&gt; iter(set);
 500
 501        for (i = -10; i &lt; 10; ++i)
 502          set.insert (2 * i + 1);
 503
 504        </pre>
 505        rather than the postfix operator:
 506        <pre>
 507        for (i = -10; i &lt; 10; i++)
 508          set.insert (2 * i + 1);
 509        </pre><p>
 510
 511     <li>Prefer using <strong> <code> if (...) else .... </code> </strong>
 512     instead of <strong> <code> ?: </code> </strong> operator. It is a lot
 513     less error prone, and will help you avoid bugs caused due to the
 514     precedence of <strong> <code> ?: </code> </strong>, compared with other
 515     operators in an expression.
 516
 517     <li>When a class provides <code>operator==</code>, it must also provide
 518         <code>operator!=</code>.  Also, both these operators must be
 519         <code>const</code> and return <code>bool</code>.
 520
 521     <li>Avoid unnecessary parenthesis.  We're not writing Lisp :-)<p>
 522
 523     <li>Put inline member functions in a <strong><code>.inl</code></strong>
 524         file.  That file is conditionally included by both the
 525         <strong><code>.h</code></strong> file, for example:<p>
 526
 527             <pre>
 528             class ACE_Export ACE_High_Res_Timer
 529             {
 530               [...]
 531             };
 532
 533             #if defined (__ACE_INLINE__)
 534             #include "ace/High_Res_Timer.inl"
 535             #endif /* __ACE_INLINE__ */
 536             </pre><p>
 537
 538         and <strong><code>.cpp</code></strong> file:<p>
 539
 540             <pre>
 541             #define ACE_BUILD_DLL
 542             #include "ace/High_Res_Timer.h"
 543
 544             #if !defined (__ACE_INLINE__)
 545             #include "ace/High_Res_Timer.inl"
 546             #endif /* __ACE_INLINE__ */
 547
 548             ACE_ALLOC_HOOK_DEFINE(ACE_High_Res_Timer)
 549             </pre><p>
 550
 551         <strong>NOTE:</strong> It is very important to ensure than an
 552         inline function will not be used before its definition is seen.
 553         Therefore, the inline functions in the .inl file should be arranged
 554         properly.  Some compilers, such as <code>g++</code> with the
 555         <code>-Wall</code> option, will issue warnings for violations.<p>
 556
 557     <li>Some inlining heuristics:<p>
 558       <ul>
 559         <li>One liners should almost always be inline, as in:
 560 <pre>
 561 ACE_INLINE
 562 Foo::bar ()
 563 {
 564   this-&gt;baz ();
 565 }
 566 </pre><p>
 567
 568         <li>The notable exception is virtual functions, which should
 569             generally not be inlined.<p>
 570
 571         <li>Big (more than 10 lines) and complex function (more than one if ()
 572           statement, or a switch, or a loop) should not be inlined.<p>
 573
 574         <li>Medium sized stuff depends on how performance critical it is.
 575           If you know that it's in the critical path, then make it
 576                 inline.  When in doubt, profile the code.<p>
 577       </ul>
 578
 579     <li><code>ACE_Export</code> must be inserted between the
 580         <code>class</code> keyword and class name for all classes that
 581         are exported from libraries, as shown in the example above.
 582         <strong>However</strong>, do <strong>not</strong> use
 583         <code>ACE_Export</code> for template classes or classes that
 584         are not used out of the ACE library, for example.!<p>
 585
 586     <li>Mutators and accessors should be of this form:<p>
 587
 588         <pre>
 589         /// Sets @c object_addr_ cache from @c host and @c port.
 590         void object_addr (const ACE_INET_Addr &);
 591
 592         /// Returns the ACE_INET_Addr for this profile.
 593         const ACE_INET_Addr &object_addr const ();
 594         </pre><p>
 595
 596         instead of the "set_" and "get_" form.<p>
 597
 598     <li>Never use <strong><code>delete</code></strong> to deallocate
 599         memory that was allocated with <strong><code>malloc</code></strong>.
 600         Similarly, never associate <strong><code>free</code></strong> with
 601         <strong><code>new</code></strong>.
 602         <strong><code>ACE_NEW</code></strong> or
 603         <strong><code>ACE_NEW_RETURN</code></strong> should be used to
 604         allocate memory, and <strong><code>delete</code></strong> should
 605         be used to deallocate it.  And be careful to use the correct form,
 606         <strong><code>delete</code></strong> or
 607         <strong><code>delete []</code></strong> to correspond to the
 608         allocation.<p>
 609
 610     <li>Don't check for a pointer being nullptr before deleting it.  It's
 611         always safe to delete a nullptr.  If the pointer is visible
 612         outside the local scope, it's often a good idea to nullptr it
 613         _after_ deleting it.  Note, the same argument applies to
 614         free().<p>
 615
 616     <li>Always use <strong><code>ACE_NEW</code></strong> or
 617         <strong><code>ACE_NEW_RETURN</code></strong> to allocate memory,
 618         because they check for successful allocation and set errno
 619         appropriately if it fails.<p>
 620
 621     <li>Never compare or assign a pointer value with <strong>NULL</strong> or <strong>0</strong>
 622         use <strong>nullptr</strong> instead.<p>
 623
 624     <li>Never cast a pointer to or from an <strong><code>int</code></strong>
 625         or a <strong><code>long</code></strong>.  On all currently supported
 626         ACE platforms, it is safe to cast a pointer to or from
 627         <strong><code>intptr_t</code></strong> or
 628         <strong><code>uintptr_t</code></strong> (include ace/Basic_Types.h).<p>
 629
 630     <li>Be very careful when selecting an integer type that must be a
 631         certain size, <em>e.g.</em>, 4 bytes.  <strong>long</strong> is
 632         not 4 bytes on all platforms; it is 8 bytes on many 64-bit
 633         machines.  ACE_UINT32 is always 4 bytes, and ACE_UINT64 is
 634         always 8 bytes.<p>
 635
 636     <li>If a class has any virtual functions, and its destructor is
 637         declared explicitly in the class, then the destructor should
 638         <strong>always</strong> be virtual as well.  And to support
 639         compiler activities such as generation of virtual tables and,
 640         in some cases, template instantiation, the virtual destructor
 641         should <strong>not be inline</strong>.  (Actually, any non-pure
 642         virtual function could be made non-inline for this purpose.  But,
 643         for convenience, if its performance is not critical, it is usually
 644         easiest just to make the virtual destructor non-inline.)<p>
 645
 646
 647     <li><a name="ACE_Time_Value example">Avoid default arguments</a>
 648         unless there's a good reason.  For an example of how they got
 649         us into a jam is:
 650         <pre>
 651         ACE_Time_Value (long sec, long usec = 0);
 652         </pre>
 653
 654         So, <code>ACE_Time_Value (2.5)</code> has the unfortunate
 655         effect of coercing the 2.5 to a long with value 2.  That's
 656         probably not what the programmer intended, and many compilers
 657         don't warn about it.<p>
 658
 659         A nice fix would be to add an <code>ACE_Time_Value (double)</code>
 660         constructor.  But, that would cause ambiguous overloading
 661         due to the default value for the second argument of
 662         <code>ACE_Time_Value (long sec, long usec = 0)</code>.
 663         We're stuck with <code>ACE_Time_Value</code>, but now we
 664         know that it's easy to avoid.<p>
 665
 666     <li>Constructor initializers must appear in the same order as
 667         the data members are declared in the class header.  This avoids
 668         subtle errors, because initialization takes place in the order
 669         of member declaration.<p>
 670
 671     <li>Initialization is usually cleaner than assignment, especially
 672         in a conditional.  So, instead of writing code like this:
 673
 674         <pre>
 675         ssize_t n_bytes;
 676
 677         // Send multicast of one byte, enough to wake up server.
 678         if ((n_bytes = multicast.send ((char *) &reply_port,
 679           sizeof reply_port)) == -1)
 680         </pre>
 681
 682         Write it like this:
 683
 684         <pre>
 685         ssize_t n_bytes = multicast.send ((char *) &reply_port,
 686           sizeof reply_port)
 687
 688         // Send multicast of one byte, enough to wake up server.
 689         if (n_bytes == -1)
 690         </pre><p>
 691
 692         But, beware if the initialization is of a static variable.
 693         A static variable is only initialized the first time its
 694         declaration is seen.  Of course, we should avoid using
 695         static (and non-constant) variables at all.<p>
 696
 697     <li>It is usually clearer to write conditionals that have
 698         both branches without a negated condition.  For example,<p>
 699
 700         <pre>
 701         if (test)
 702           {
 703             // true branch
 704           }
 705         else
 706           {
 707             // false branch
 708           }
 709         </pre><p>
 710
 711         is preferred over:<p>
 712
 713         <pre>
 714         if (! test)
 715           {
 716             // false test branch
 717           }
 718         else
 719           {
 720             // true test branch
 721           }
 722         </pre><p>
 723
 724     <li>If a cast is necessary, avoid use of C-style "sledgehammer"
 725             casts.  Use standard C++ casts
 726             (e.g. <code>static_cast&lt;int&gt; (foo)</code>) instead.<p>
 727
 728     <li>In general, if instances of a class should not be copied,
 729         then a private copy constructor and assignment operator should
 730         be deleted for the class
 731
 732         <pre>
 733         // Disallow copying by not implementing the following . . .
 734         ACE_Object_Manager (const ACE_Object_Manager &) = delete;
 735         ACE_Object_Manager (ACE_Object_Manager &&) = delete;
 736         ACE_Object_Manager &operator= (const ACE_Object_Manager &) = delete;
 737         ACE_Object_Manager &operator= (ACE_Object_Manager &&) = delete;
 738         </pre><p>
 739
 740     <li>Never use <code>BOOL</code>, or similar types.
 741             (<code>ACE_CDR::Boolean</code> and
 742             <code>CORBA::Boolean</code> are acceptable).  Use the
 743             standard C++ <code>bool</code> for boolean variables, instead.<p>
 744
 745     <li>Functions should always return -1 to indicate failure, and
 746         0 or greater to indicate success.<p>
 747
 748     <li>Separate the code of your templates from the code for
 749         non-parametric classes: some compilers get confused when
 750         template and non-template code is mixed in the same file.<p>
 751
 752     <li>It's a good idea to specify the include path (with <code>-I</code>)
 753         to include any directory which contains files with template
 754         definitions.<p>
 755
 756     <li>When referring to member variables and functions, use
 757         <code>this-&gt;</code><em>member</em>. This makes it clear to the
 758         reader that a class member is being used. It also makes it crystal
 759         clear to the compiler which variable/function you mean in cases
 760         where it might make a difference. <p>
 761
 762     <li>Don't use template template arguments, this C++ construct is not
 763         supported by the HP aCC 3.70 compiler at this moment. For example the
 764   following template decleration is one that just doesn't work.
 765         <pre>
 766         template&lt;typename S_var, size_t BOUND, template &lt;typename&gt; class Insert_Policy&gt; class A {};
 767         </pre>
 768   </ul>
 769   <li><strong>I/O</strong><p>
 770   <ul>
 771      <li>Use <strong><code>ACE_DEBUG</code></strong> for printouts,
 772          and <strong><code>ACE_OS::fprintf ()</code></strong> for
 773          file I/O.  Avoid using iostreams because of implementation
 774          differences across platforms.<p>
 775      <li>After attempting to open an existing file, always check for success.
 776          Take appropriate action if the open failed.<p>
 777      <li>Notice that <strong><code>ACE_DEBUG</code></strong> and
 778          <strong><code>ACE_ERROR</code></strong> don't support
 779          <code>%ld</code> of any other multicharacter format.<p>
 780   </ul>
 781
 782   <li><strong>WCHAR conformity</strong><p>
 783
 784   <ul>
 785      <li>For ACE, use <code>ACE_TCHAR</code> instead of char for strings and <code>ACE_TEXT()</code>
 786          around string literals.  Exceptions are <code>char</code>
 787             arrays used for data  and strings that need to remain as 1
 788             byte characters.
 789
 790      <li>If you have a char string that needs to be converted to <code>ACE_TCHAR</code>,
 791          use the <code>ACE_TEXT_CHAR_TO_TCHAR()</code> macro.  If you have a <code>ACE_TCHAR</code>
 792          string that needs to be converted to a <code>char</code> string, use the
 793          <code>ACE_TEXT_ALWAYS_CHAR()</code> macro
 794
 795      <li>Do not use the Win32 <code>TCHAR</code> macros.  The wide character-ness of ACE
 796          is separate from UNICODE and _UNICODE.
 797
 798      <li>If you have a <code>printf</code>-like format specifier that
 799          uses <code>%s</code> to format a string, certain WCHAR implementations
 800          require <code>%ls</code> instead.
 801          The macro <code>ACE_TEXT_PRIs</code> contains <code>"s"</code> or <code>"ls"</code>
 802          depending upon the WCHAR implementation, and may be used as
 803          <code>ACE_TEXT("%") ACE_TEXT_PRI_s</code>, where the first argument may also
 804          contain flags and width specifiers.
 805
 806      <li>For TAO, don't use <code>ACE_TCHAR</code> or <code>ACE_TEXT</code>.  The CORBA specification
 807          defines APIs as using char.  So most of the time there is no need
 808          to use wide characters.
 809   </ul><P>
 810
 811   <li><strong>Exceptions</strong><p>
 812
 813   <ul>
 814     <li>There are many ways of throwing and catching exceptions. The
 815         code below gives several examples.  Note that each method has
 816         different semantics and costs. Whenever possible, use the
 817         first approach.<p>
 818
 819         <pre>
 820         #include "iostream.h"
 821
 822         class exe_foo
 823         {
 824         public:
 825           exe_foo (int data) : data_ (data)
 826             { cerr &lt;&lt; "constructor of exception called" &lt;&lt; endl; }
 827           ~exe_foo ()
 828             { cerr &lt;&lt; "destructor of exception called" &lt;&lt; endl; }
 829           exe_foo (const exe_foo& foo) : data_ (foo.data_)
 830             { cerr &lt;&lt; "copy constructor of exception called"
 831                    &lt;&lt; endl; }
 832           int data_;
 833         };
 834
 835
 836         void
 837         good (int a)
 838         {
 839           throw exe_foo (a);
 840         };
 841
 842         void
 843         bad (int a)
 844         {
 845           exe_foo foo (a);
 846           throw foo;
 847         };
 848
 849         int main ()
 850         {
 851           cout &lt;&lt; endl &lt;&lt; "First exception" &lt;&lt; endl
 852                &lt;&lt; endl;
 853           try
 854             {
 855               good (0);
 856             }
 857           catch (exe_foo &foo)
 858             {
 859               cerr &lt;&lt; "exception caught: " &lt;&lt; foo.data_
 860                    &lt;&lt; endl;
 861             }
 862
 863           cout &lt;&lt; endl &lt;&lt; "Second exception" &lt;&lt; endl
 864                &lt;&lt; endl;
 865           try
 866             {
 867               good (0);
 868             }
 869           catch (exe_foo foo)
 870             {
 871               cerr &lt;&lt; "exception caught: " &lt;&lt; foo.data_
 872                    &lt;&lt; endl;
 873             }
 874
 875           cout &lt;&lt; endl &lt;&lt; "Third exception" &lt;&lt; endl
 876                &lt;&lt; endl;
 877           try
 878             {
 879               bad (1);
 880             }
 881           catch (exe_foo &foo)
 882             {
 883               cerr &lt;&lt; "exception caught: " &lt;&lt; foo.data_
 884                    &lt;&lt; endl;
 885             }
 886
 887           cout &lt;&lt; endl &lt;&lt; "Fourth exception" &lt;&lt; endl
 888                &lt;&lt; endl;
 889           try
 890             {
 891               bad (1);
 892             }
 893           catch (exe_foo foo)
 894             {
 895               cerr &lt;&lt; "exception caught: " &lt;&lt; foo.data_
 896                    &lt;&lt; endl;
 897             }
 898
 899           return 0;
 900         }
 901         </pre>
 902
 903      Output is: <p>
 904
 905         <pre>
 906         First exception
 907
 908         constructor of exception called
 909         exception caught: 0
 910         destructor of exception called
 911
 912         Second exception
 913
 914         constructor of exception called
 915         copy constructor of exception called
 916         exception caught: 0
 917         destructor of exception called
 918         destructor of exception called
 919
 920         Third exception
 921
 922         constructor of exception called
 923         copy constructor of exception called
 924         destructor of exception called
 925         exception caught: 1
 926         destructor of exception called
 927
 928         Fourth exception
 929
 930         constructor of exception called
 931         copy constructor of exception called
 932         destructor of exception called
 933         copy constructor of exception called
 934         exception caught: 1
 935         destructor of exception called
 936         destructor of exception called
 937
 938         </pre>
 939
 940       </ul><p>
 941
 942   <li><strong>Compilation</strong><p>
 943   <ul>
 944     <li>Whenever you add a new test or example to ACE or TAO, make
 945         sure that you modify the MPC file in the parent directory.
 946       This will make sure that your code gets compiled on a
 947       regular basis.<p>
 948   </ul><p>
 949 </ul>
 950
 951 <hr>
 952 <h3><a href="http://www.dre.vanderbilt.edu/~schmidt/ACE-overview.html">ACE</a>
 953   Shared Libary Guidelines</h3>
 954     <ul>
 955       <li>
 956         <p>
 957           Create a separate export macro for each dynamic library.  A
 958           header file containing the export macro and additional
 959           support macros should be generated by using the <a
 960             href="../bin/generate_export_file.pl">ACE_wrappers/bin/generate_export_file.pl</a> Perl script.
 961           </p>
 962       </li>
 963       <li>
 964         <p>
 965           Make sure that your classes, structures and free functions
 966           are annotated with this export macro.  The only exceptions
 967           are pure template classes, structures and free functions.
 968         </p>
 969         <p>
 970           Only classes (and structures, free functions, etc) that are
 971           part of the library public interface must be exported
 972           (e.g. declared with an export macro).  Those that are only
 973           meant to be used internally need not be exported,
 974           particularly for g++ <code>&gt;=</code>4.0  since doing so
 975           defeats some neat optimizations.  Here's a common case in
 976           where an export macro is generally used unnecessarily:
 977         </p>
 978         <blockquote>
 979           <pre>
 980 class FooExport Foo
 981 {
 982 public:
 983   virtual void kung_fu () = 0;
 984 };
 985
 986 class FooExport Bar : public Foo
 987 {
 988 public:
 989   virtual void kung_fu ()  { ... }
 990 };
 991
 992 class FooExport FooFactory
 993 {
 994 public:
 995   Foo * make_foo ()
 996     {
 997       // Assume that this implementation is hidden from
 998       // the application and is consequently out of line.
 999       return new Bar();
1000     }
1001 };
1002           </pre>
1003         </blockquote>
1004         <p>
1005           Here the application is only meant to invoke operations
1006           through a pointer or reference to the abstract base class
1007           "<code>Foo</code>" created by the "<code>FooFactory</code>",
1008           not the "<code>Bar</code>" subclass.  In this case,
1009           exporting "<code>Bar</code>" is unnecessary.  If your
1010           concrete class is meant to be used outside of the shared
1011           library (e.g. as a template parameter, within a
1012           <code>dynamic_cast&lt;&gt;</code>, etc) you must then export
1013           it.  Otherwise, avoid doing so if you can.
1014         </p>
1015       </li>
1016       <li>
1017         <p>
1018           Make sure that you specify that you are creating a dynamic
1019           library in your <a href="../MPC/README">MPC</a> file by adding
1020           a <code>sharedname</code> tag.
1021         </p>
1022       </li>
1023       <li>
1024         <p>
1025           Make sure that you add the <code>FOO_BUILD_DLL</code>
1026           preprocessor symbol to the <code>dynamicflags</code> of the
1027           MPC project that is used to build a library.  Note that the
1028           export files are setup such that when this macro is defined,
1029           the symbols are exported, otherwise they are imported.  The
1030           default behaviour is to set up for import so that clients of
1031           your library don't need to worry about arcane build flags
1032           like <code>FOO_BUILD_DLL</code> in their build setup.  This
1033           ties back to the first item.
1034         </p>
1035       </li>
1036       <li>
1037         <p>
1038           When you specify the order of libraries to link to, make
1039           sure that the dependent libraries come after the libraries
1040           which depend on them, i.e., your link line should always
1041           contain <code>-lDependsOnFoo -lFoo</code>.  Note that this
1042           is not a requirement on GNU/Linux but linkers on other
1043           platforms are not as forgiving.
1044         </p>
1045       </li>
1046       <li>
1047         <p>
1048           Use the <code>ACE_SINGLETON_DECLARE</code> macro to declare
1049           a class as a singleton.  Declare exported (i.e. default
1050           visibility)  singleton templates prior to typedefs that
1051           reference them.  This prevents g++ 4.0 from silently making
1052           their visibility hidden (see <a
1053             href="http://bugzilla.dre.vanderbilt.edu/show_bug.cgi?id=2260">Bug 2260</a> for details).
1054         </p>
1055       </li>
1056       <li>
1057         <p>
1058           Avoid inlining virtual functions in classes that must be
1059           exported since doing so can cause RTTI related problems
1060           (e.g. <code>dynamic_cast&lt;&gt; failures</code>) when using
1061           g++ &gt;= 4.0 due to our use of that compiler's "visibility
1062           attribute" support that is tied in to the export macros.
1063           This includes virtual destructors automatically created by
1064           the compiler when you don't declare one.  Make sure you
1065           define a no-op out-of-line virtual destructor if your base
1066           class has a virtual destructor since you may otherwise run
1067           into the mentioned RTTI problems.
1068         </p>
1069       </li>
1070     </ul>
1071
1072
1073 <hr>
1074 <h3><a href="http://www.dre.vanderbilt.edu/~schmidt/ACE-overview.html">ACE</a>
1075   Usage Guidelines</h3>
1076 <ul>
1077   <li>Always use the <strong><code>ACE_OS</code></strong>
1078       namespace functions instead of bare OS system calls.<p>
1079
1080   <li>As a general rule, the only functions that should go into the
1081       <strong><code>ACE_OS</code></strong> namespace are ones that
1082         have direct equivalents on some OS platform.  Functions that
1083         are extensions should go in the
1084         <strong><code>ACE</code></strong> namespace.<p>
1085
1086   <li>Use the <strong><code>ACE_SYNCH_MUTEX</code></strong> macro,
1087       instead of using one of the specific mutexes, such as
1088       <strong><code>ACE_Thread_Mutex</code></strong>.  This provides
1089       portability between threaded and non-threaded platforms.<p>
1090
1091   <li>Avoid creating a static instance of user-defined (class) type.
1092       Instead, either create it as an
1093       <strong><code>ACE_Singleton</code></strong>,
1094       <strong><code>ACE_TSS_Singleton</code></strong>, or as an
1095       <strong><code>ACE_Cleanup</code></strong> object.  See the
1096       <strong>ACE</strong>
1097       <a href="../ace/Singleton.h"><code>Singleton.h</code></a>,
1098       <a href="../ace/Object_Manager.h"><code>Object_Manager.h</code></a>, and
1099       <a href="../ace/Managed_Object.h"><code>Managed_Object.h</code></a>
1100       header files for more information.<p>
1101
1102       Static instances of built-in types, such as
1103       <strong><code>int</code></strong> or any pointer type, are fine.<p>
1104
1105       Construction of static instance of a user-defined type should
1106       <em>never</em> spawn threads.  Because order of construction of
1107       statics across files is not defined by the language, it is usually
1108       assumed that only one thread exists during static construction.
1109       This allows statics suchs as locks to be safely created.  We do not
1110       want to violate this assumption.<p>
1111
1112   <li>Do not use C++ exception handling directly.  Some platforms do
1113       not support it.  And, it can impose an execution speed penalty.
1114       Instead use the TAO/ACE try/catch macros.<p>
1115
1116   <li>Because ACE does not use exception handling, dealing with
1117       failures requires a bit of care.  This is especially true
1118       in constructors.  Consider the following approach:
1119
1120       <pre>
1121       ACE_NEW_RETURN (this-&gt;name_space_, LOCAL_NAME_SPACE, -1);
1122
1123       if (ACE_LOG_MSG-&gt;op_status () != 0)
1124       ....
1125       </pre>
1126
1127       This snip of code is from
1128       <a href="../ace/Naming_Context.cpp"><code>ACE_Naming_Context</code></a>.
1129       All failed constructors in ACE (should) call ACE_ERROR.  This sets
1130       the thread-specific <strong>op_status</strong>, which can be checked
1131       by the caller.  This mechanism allows the caller to check for a failed
1132       constructor without the requiring the constructor to throw
1133       exceptions.<p>
1134
1135   <LI>Another consequence of ACE's avoidance of exception handling is
1136       that you should use <CODE>open()</CODE> methods on classes that
1137       perform initializations that can fail.  This is because <CODE>open()</CODE>
1138       returns an error code that's easily checked by the caller,
1139       rather than relying on constructor and thread-specific status
1140       values. <P>
1141
1142   <li>Avoid using the C++ Standard Template Library (STL) in our
1143       applications.  Some platforms do not support it yet. It is
1144       safe to use the STL generic algoritms. The following have been
1145       used already and don't seem to cause any portability issues:
1146       <pre>
1147   std::swap
1148   std::for_each
1149   std::fill
1150   std::generate
1151   std::transform
1152   std::copy
1153       </pre><p>
1154
1155   <li>Be <em>very</em> careful with <code>ACE_ASSERT</code>.  It
1156       must only be used to check values; it may never be used to
1157       wrap a function call, or contain any other side effect.  That's
1158       because the statement will disappear when ACE_NDEBUG is enabled.
1159       For example, this code is BAD:
1160       <pre>
1161       ACE_ASSERT (this-&gt;next (retv) != 0);  // BAD CODE!
1162       </pre>
1163
1164       Instead, the above should be coded this way:
1165
1166       <pre>
1167       int const result = this-&gt;next (retv);
1168       ACE_ASSERT (result != 0);
1169       ACE_UNUSED_ARG (result);
1170       </pre><p>
1171
1172   <li>Never put side effects in <code>ACE_DEBUG</code> code:
1173       <pre>
1174       ACE_DEBUG ((LM_DEBUG,
1175                  "handling signal: %d iterations left\n",
1176                  --this-&gt;iterations_));        // BAD CODE!
1177       </pre>
1178
1179       Note that this won't work correctly if <code>ACE_NDEBUG</code> is
1180       defined, for the same reason that having side-effects in
1181       <code>ACE_ASSERT</code>s won't work either, <em>i.e.</em>, because
1182       the code is removed.<p>
1183
1184   <li>Be <strong>very</strong> careful with the code that you put
1185       in a signal handler. In general, it's best to just set a flag in a signal
1186       handler and take appropriate action elsewhere.  It's also best
1187       to avoid using signals, especially asynchronous signals.<p>
1188
1189   <li>Immediately after opening a temporary file, unlink it.  For
1190       example:
1191       <pre><code>
1192       ACE_HANDLE h = open the file (filename);
1193
1194       ACE_OS::unlink (filename);
1195       </code></pre><p>
1196
1197       This avoids leaving the temporary file even if the program crashes.<p>
1198
1199   <li>Be sure to specify the <code>THR_BOUND</code> thread creation
1200     flag for time-critical threads. It is harmless on other platforms.<p>
1201 </ul>
1202
1203
1204 <hr>
1205 <h3><a href="http://www.dre.vanderbilt.edu/~schmidt/ACE-overview.html">Other
1206   ACE</a> and
1207   <a href="http://www.dre.vanderbilt.edu/~schmidt/TAO-overview.html">TAO</a>
1208   Guidelines</h3>
1209 <ul>
1210   <li>When enhancing, updating, or fixing ACE or TAO, always:
1211   <ol>
1212     <li>Test your change on at least Windows and Linux before committing.
1213       After committing watch the scoreboard to catch errors your change
1214       may be related to on other platforms.
1215     <li>If the change is in response to a request by someone else:
1216     <ol>
1217       <li>Make sure that person is acknowledged in
1218         <a href="../THANKS">ACE_wrappers/THANKS</a>, and<p>
1219       <li>Respond to that person.<p>
1220     </ol>
1221   </ol>
1222
1223   <li><strong>Never</strong> add copyrighted, confidential, or otherwise
1224       restricted code to the ACE or TAO distributions without reviewing
1225       the situation with DOC management (i.e. Doug Schmidt). You will also
1226       most likely need to get written permission from the owner. The
1227       particular language and form needed will be relayed to you after
1228       discussing it with DOC management.<p>
1229 </ul>
1230
1231
1232 <hr>
1233 <h3>Git Usage Guidelines</h3>
1234 <ul>
1235   <li>Always make sure that a change builds and executes correctly
1236     on at least one platform before checking it into the git repository.
1237     All changes <strong>must</strong> be tested with g++ before committing.
1238     That means you may need to test on at least two platforms.<p>
1239 </ul>
1240
1241
1242 <hr>
1243 <h3>Script Guidelines</h3>
1244 <ul>
1245   <li>In general, it's best to write scripts in Perl.  It's
1246     OK to use Bourne shell.  Never, never, never use csh, ksh,
1247     bash, or any other kind of shell.<p>
1248
1249   <li>Follow the Perl style guide guide as closely as
1250     possible.  <code>man perlstyle</code> to view it.
1251
1252   <li>Don't specify a hard-coded path to Perl itself.  Use
1253     the following code at the top of the script to pick up
1254     perl from the users <code>PATH</code>:<br>
1255       <pre>
1256 eval '(exit $?0)' && eval 'exec perl -S $0 ${1+"$@"}'
1257     & eval 'exec perl -S $0 $argv:q'
1258     if 0;
1259       </pre><p>
1260
1261   <li>Never, never, never start the first line of a script
1262     with "<code>#</code>", unless the first line is "<code>#! /bin/sh</code>".
1263     With just "<code>#</code>", t/csh users will spawn a new shell.
1264     That will cause their <code>.[t]cshrc</code> to be
1265     processed, possibly clobbering a necessary part of
1266     their environment.<p>
1267
1268   <li>If your Perl script relies on features only available
1269     in newer versions of Perl, include the a statement similar
1270     to the following:<br>
1271       <pre>
1272         require 5.003;
1273       </pre>
1274
1275   <li>Don't depend on <strong><code>.</code></strong> being
1276     in the user's path.  If the script spawns another executable
1277     that is supposed to be in the current directory, be sure the
1278     prefix its filename with <strong><code>.</code></strong>.<p>
1279 </ul>
1280
1281
1282 <hr>
1283 <h3>Software Engineering Guidelines</h3>
1284 <ul>
1285   <li><strong>Advise</strong>:  Keep other developers informed of problems
1286       and progress.<p>
1287
1288   <li><strong>Authorize</strong>:  We have contractual obligations to not
1289       unilaterally change interfaces.  If you need to change or remove an
1290       interface, get an OK.<p>
1291
1292   <li><strong>Minimize</strong> risk:  Test all changes.  Solicit review of
1293       changes.<p>
1294
1295   <li><strong>Revise</strong> only when necessary:  Every change has risk,
1296       so avoid making any change unless there is a good reason for it.<p>
1297
1298   <li><strong>Normalize</strong>:  Factor out commonality.  For example,
1299       maintain a data value in only one place.<p>
1300
1301   <li><strong>Synthesize</strong>:  Build stubs and scaffolding early to
1302       simulate the complete system.  Maintain a checked-in version of the
1303       system that cleanly builds and tests at all times.<p>
1304
1305   <li><strong>Be available</strong>:  Breaking compilation in one
1306       platform or another should be avoided (see above),
1307       but it is bound to happen when so many platforms are in use.
1308       Be available after making a change,
1309       if you won't be available for at least 48 hours after the change
1310       is made then don't make it!<p>
1311 </ul>
1312
1313 <hr>
1314 Back to <A HREF="index.html">ACE Documentation Home</A>.
1315
1316 </body>
1317 </html>