source/README.7coding

   1 (This file was generated by makeinfo and splitinfo.gawk.)
   2 (Released under the old-style GNU documentation license;
   3  see sources or other output files for full text.)
   4
   5 9 Coding conventions
   6 ********************
   7
   8 Ideally, building all of TeX Live with '--enable-compiler-warnings=max'
   9 should produce no (GCC) compiler warnings at all.  In spite of
  10 considerable efforts into that direction we are still far from that goal
  11 and there are reasons that we may never fully reach it.  Below are some
  12 rules about declarations of functions or variables and the use of
  13 'const'.  These rules should be applied to all parts of the TeX Live
  14 tree, except some of those maintained independently.
  15
  16 9.1 Declarations and definitions
  17 ================================
  18
  19 C standards
  20 ...........
  21
  22 The TeX Live build system no longer supports pre-ANSI C compilers.  Thus
  23 all function prototypes and definitions must conform to the ANSI C
  24 standard (including 'void' in the declaration of C functions with no
  25 parameters).  On the other hand, TL is built for a wide variety of
  26 systems, not all of which support the C99 standard.  Therefore using C99
  27 features should be avoided if that can easily be done.  In particular C
  28 code must not contain declarations after statements or C++-style
  29 comments.
  30
  31    If some C99 (or later) constructs must be used, the module should
  32 verify that they are available and otherwise provide an alternative.
  33 For example, the module 'texk/chktex' uses the C99 function 'stpcpy()'
  34 that may or may not be available on a particular system.  It uses
  35 'AC_CHECK_DECLS([stpcpy])' in 'configure.ac' to test this, and provides
  36 the perhaps slightly less efficient alternative
  37
  38      #if !(defined HAVE_DECL_STPCPY && HAVE_DECL_STPCPY)
  39      static inline char *stpcpy(char *dest, const char *src)
  40      {
  41        return strcpy(dest, src) + strlen(src);
  42      }
  43      #endif
  44
  45 in the file 'Utility.h'.
  46
  47 Static functions
  48 ................
  49
  50 Functions used in only one file should be declared 'static'; they
  51 require no prototype except as forward declaration.
  52
  53 Extern functions
  54 ................
  55
  56 Functions not declared 'static', usually because they are used in
  57 several files, require an ('extern') prototype in exactly one header
  58 file, which is included in the file defining the function and in all
  59 files using that function--this is the only way to guarantee consistency
  60 between definition and use.  There should be no 'extern' declarations
  61 sprinkled throughout the C code (with or without comments as to where
  62 that function is defined).
  63
  64 Variable declarations
  65 .....................
  66
  67 The declaration of global variables follows analogous rules: they are
  68 either declared 'static' if used in only one file or declared 'extern'
  69 in exactly one header and instantiated in exactly one file.
  70
  71 9.2 Const
  72 =========
  73
  74 The 'const' feature of C is valuable, but easy to mis-use.
  75
  76 Function parameters
  77 ...................
  78
  79 Ideally, a function parameter not modified by the function should be
  80 declared as 'const'.  This is important in particular for strings
  81 ('char*') because the actual arguments are often string literals.  It is
  82 perfectly legitimate and safe to use a type 'char*' value for a type
  83 'const char*' variable (in an assignment, as initializer, as function
  84 argument, or as return value).  It is equally safe to use a type
  85 'char**' value for a type 'const char*const*' variable, but not for a
  86 type 'const char**' variable since that might cause modification of a
  87 quantity supposed to be constant.
  88
  89    Getting all 'const' qualifiers right can get quite involved but can
  90 almost always be done.  There are only a couple notable exceptions: the
  91 X11 headers are full of declarations that ought to use 'const' but do
  92 not, and the same is true to some extent for 'libfreetype' (but,
  93 thankfully, not for 'zlib' nowadays).
  94
  95 What must be avoided with 'const'
  96 .................................
  97
  98 The GCC compiler warnings "assignment discards qualifiers..." and
  99 analogous warnings for "initialization", "passing arg", or "return" must
 100 be strenously avoided in our own code.  The only exception is when they
 101 are caused by X11 headers or macros or other third party code.
 102
 103 What should be avoided with 'const'
 104 ...................................
 105
 106 A type cast, e.g., from 'const char*' to 'char*' does not solve any
 107 problems; depending on warning options, it may only hide them.
 108 Therefore such casts should be avoided whenever possible and otherwise
 109 must be carefully analyzed to make sure that they cannot cause the
 110 modification of quantities supposed to be constant.
 111