A brief summary of the checks performed by "codingcheck" and the
reasons for them.  

1. #ifdef and #define names:  We want to use a prefix on these in
   order to avoid clashes with other systems that aren't careful
   about names.  One vendor defined CACHE_ALIGN, which broke code
   used in MPICH1 to cache align data structures.  Prefixes should be
   USE_, NEEDS_, HAVE_, WITH_, MPIR_, MPID_ . 

   In some cases, a nonconforming name may be needed. For example, 
   a system may require that you define INET6 to get the desired 
   behavior.  In these cases, add the appropriate tests to 
   configure to determine if the definition is in fact needed, and define
   NEEDS_name_DEFINED in that case.  In the narrowest scope possible, add
   # ifdef NEEDS_name_DEFINED
   # define name
   # endif

2. malloc/free/calloc/realloc/strdup: By using the MPIU_xxx routines,
   it is easier to check for storage overwrites and leaks, even on
   systems (or at scales) where we don't have more sophisticated tools
   for trapping memory problems.  Since these can be replaced by
   macros that directly call malloc etc., there is no performance
   overhead.  The header file src/include/mpimem.h contains definitions for 
   the MPIU_xxx routines for memory management, including definitions
   that replace these with malloc etc.

3. printf/fprintf: To allow for internationalization, all messages
   that users may see should go through MPIU_Usage_printf,
   MPIU_Msg_printf, MPIU_Error_printf, and MPIU_Internal_error_printf
   (this also helps separate messages that are intended for users and
   ones that represent some internal error that a user may see if
   something goes wrong).  Debugging messages should be either wrapped
   in MPIDEBUG(...) (as in MPIDEBUG(printf( ....))) or use DBG_PRINTF and
   DBG_FPRINTF.   

4. C++ files should use a C++ suffix (cxx is used by the C++ binding and 
   appears to be the only suffix recognized by all compilers).  C++ header
    files should set the Emacs mode to C++, as in 
    /* -*- Mode: C++;  c-basic-offset:4 ; -*- */  

   // is not a valid C comment.  C files that use // are *BROKEN*.  
   Please take responsibility for these and *FIX THEM*!!!!

5. strcpy etc.: The standard C routines are very dangerous, since it
   is easy for them to allow an overwrite of memory.  The versions in
   src/util/mem/safestr.c are safer than the standard strcpy etc but
   do not access the entire array (e.g., strncpy sets n characters,
   not the min of (n,length of source string+1, MPIU_Strncpy does do
   only the min).  For sprint, use MPIU_Snprintf instead; this is just
   snprintf where snprintf is available but provides a partial
   implementation (just %s, %d, and %% + regular characters) for
   systems without snprintf. BTW, in going through the code, I found
   an strncpy( a, argv[i], strlen(argv[i])+1 ), whoever wrote this
   abomination owes a round of drinks for the group :). 

6. NMPI_xxx routines should only be used when the error handler has
   switched to errors return; this is easily done with the error nesting
   calls, and these can be nested, so that is it safe to use these for
   routines that may be called from inside a routine that has set 
   a nested call.  Also, if the call is very simple and cannot have an
   error, consider inlining the effect (e.g., use comm_ptr->local_size 
   instead of NMPI_Comm_size).

   For internal routines which you are certain will *always* be called 
   from another routine that will ensure the MPIR_Nest_incr/decr calls, you
   can use 
     /* begin:nested */
     code that would need MPIR_Nest_incr/decr
     /* end:nested */

7. There are always exceptions.  These can be handled either by
   telling the code checker to skip a file (appropriate only for
   external files, such as crypt.h), or by enhancing the code checker.
   For example, in working on the printf stuff, I realized that we
   needed to separate out user errors and internal errors for messages
   (I should have thought of this; Pete Bradley's been saying this).
   Of course, there are other things to check for as well.  If there
   is something you think we should be checking for (and an easy way
   to do it), please contribute it. 

8. By default, the codechecks ignore directories that are named
   "test".  This provides an easy way to both clearly separate these
   programs (we've had bug reports about the test programs because
   they were in the source directory) and avoid complaints from the
   code checker.  Running the code checker over them is still possible
   (and a good idea) with the option -checktest (to maint/codingcheck)

9. The perl program "checkforglobs" looks at the generated library and
   lists any global names that do not conform to the naming rules.  There
   are two types of problems: One is names that don't have one of the 
   permitted prefixed (e.g., MPI_ or PMI_).  The other is symbols that are
   "Common" rather than "Text".  Common symbols are often uninitialized 
   global variables.  While these are allowed in most Unix systems, Mac OSX 
   will not load common symbols from libraries, causing unsatisfied 
   external referneces.  These checks are run as part of the nightly runs.

Other Recommendations
Or things not checked for but desired

1. Installation scripts should use the install program, not cp, to 
   install files.  There are special targets in simplemake that let
   simplemake know which files are installed so that the correct commands
   can be generated.

2. Special compiler options for compilation.  The various flavors of Unix 
   all have their own unique functions, some of which we'll want to use.  
   In looking through a header file, it is common to see something like

   #   ifdef __USE_BSD
   # define <some incredibly useful function>
   #   endif

   and then decide to do
   #define __USE_BSD
   in a header file.

   Don't do this.  Formally, users should never define anything that starts
   with __ (two underscores).  The reason is that these names are used by the
   compilation system, and they may have strange interactions, particularly if
   they expect that other definitions are made.  Instead, try to find out how
   to put the compiler into this mode.  If the compiler doesn't *have* a mode
   for this, then try to avoid depending on these functions.  Under Linux, the
   proper definitions may be found in the file /usr/include/features.h .  For
   example, to get the BSD features, the correct approach is to define
   _BSD_SOURCE rather than __USE_BSD.

3. Macros with comparisons.  Make sure that these are parenthesized.  E.g.,
     #define foo(a) ((a) > 1)
   not
     #define foo(a) a > 1

4. Enum lists must *not* end with a trailing comma.  Some C compilers
   will not accept this.  When appending a list, use leading, not trailing
   commas.  Alternately, make all enum lists end with a "last_element", e.g.,

    enum { a, b, c,
       MACRONAME1
       MACRONAME2
       lastvalue };
