doc/STYLE

   1 GNU m4 STYLE - The way this code should look.           -*- outline -*-
   2
   3 Before all else this code follows the GNU coding standards and
   4 indentation style described in standards.info.  Additionally the
   5 following restrictions on coding style apply:
   6
   7 * SPACING
   8
   9   + Avoid TABs in .h and .c files.  See HACKING for details.
  10
  11 * C STANDARD
  12
  13   + All of this code is ANSI-C, GNU C extensions are conditional so that
  14     the code will compile cleanly on non GLIBC/GCC systems.
  15
  16 * SYMBOL NAMES
  17
  18   + All non-static symbols have a prefix either `M4' or `m4'.
  19
  20   + All exported symbols which are part of the library api have the
  21     prefix `m4_'.
  22
  23   + Symbols which are exported from the library (for efficiency perhaps)
  24     but are not part of the supported library api have the prefix
  25     `m4__',
  26
  27   + Function names should be verb phrases; m4_module_get_field.
  28
  29   + Functions which exist to be used as callbacks from API functions, and
  30     hence which likely have strange looking parameters are named with the
  31     suffix `_CB', to make it obvious why they look a little odd.
  32
  33   + Macros which implement fast versions of functions share the
  34     same name as the function they replace, and may not evaluate
  35     parameters more than once.
  36
  37   + Otherwise macros are in uppercase, prefixed `M4' if they are visible
  38     to the user after installation, to help the user know when to be
  39     careful about multiple evaluations of parameters.
  40
  41   + Function names should contain the name of the module they belong to,
  42     usually immediately after the namespace prefix: m4_module_load.
  43
  44   + Variables should not be exported (not true, but I'm working on it),
  45     but accessor functions used instead.  Note the `get'/`set' part of
  46     the symbol name comes before the module part: m4_get_module_macros.
  47
  48   + Structures come with accessor macros named <struct name>_<field
  49     name> (in upper case), to make refactoring of nested structures much
  50     easier: SYMBOL_FLAGS.
  51
  52   + Structures are typedeffed separately, and the structure itself
  53     generally not exported unless in the `m4__' namespace to support
  54     fast accessor macros.
  55
  56   + An opaque abstract data type (ADT) can have public and private fields:
  57     By convention public fields will have exported accessor functions (and
  58     maybe also fast macro versions of the same), and private fields will
  59     not export accessors at all.  However, there should be non-exported
  60     (or at least in the `m4__' namespace) accessor functions for even the
  61     private fields of an ADT to aid possible later refactoring.
  62
  63 * ARCHITECTURE
  64
  65   + There are four groups of sources in subdirectories: `gnu' contains
  66     the files maintained outside of m4, as a portability layer when building
  67     the souce for non-glibc2 machines; `m4' contains the functionality for
  68     libm4 and enables the user to write modules; `modules' implements the
  69     builtin macros for the m4 binary; `src' is a small wrapper program
  70     which links libm4 and loads initial modules to implement the m4 engine.
  71
  72   + The headers in gnu need to be managed carefully: gnulib headers
  73     can be included by other files in the same directory using `#include
  74     "file.h"', and from files in other directories with `#include
  75     <m4/file.h>'.  The include path to invocations of the compiler from
  76     various Makefile.am are set to prevent the possibility of picking up
  77     an m4/file.h when the system file.h (e.g stdbool.h) is present.  This,
  78     in turn means the replacement headers can live in gnulib/m4 without
  79     suffering a renaming scheme at configure time.  Don't break with the
  80     `#include' convention, or the compile will go wrong in hard to debug
  81     ways on some platforms.
  82
  83   + Low coupling.  Classes (and in C, by this I mean files of functions)
  84     should not rely on a web of other classes to be useful, they should
  85     communicate with as few other classes as possible.
  86
  87   + High cohesion.  The api and caller boundaries should be well defined
  88     and adhered to; a class should do one thing only.
  89
  90 ========================================================================
  91
  92 Copyright (C) 2003, 2006, 2010, 2013-2014 Free Software Foundation, Inc.
  93
  94 Permission is granted to copy, distribute and/or modify this document
  95 under the terms of the GNU Free Documentation License, Version 1.3 or
  96 any later version published by the Free Software Foundation; with no
  97 Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
  98 Texts.  A copy of the license is included in the ``GNU Free
  99 Documentation License'' file as part of this distribution.