| GNU m4 STYLE - The way this code should look. -*- outline -*- | |
| Before all else this code follows the GNU coding standards and | |
| indentation style described in standards.info. Additionally the | |
| following restrictions on coding style apply: | |
| * SPACING | |
| + Avoid TABs in .h and .c files. See HACKING for details. | |
| * C STANDARD | |
| + All of this code is ANSI-C, GNU C extensions are conditional so that | |
| the code will compile cleanly on non GLIBC/GCC systems. | |
| * SYMBOL NAMES | |
| + All non-static symbols have a prefix either `M4' or `m4'. | |
| + All exported symbols which are part of the library api have the | |
| prefix `m4_'. | |
| + Symbols which are exported from the library (for efficiency perhaps) | |
| but are not part of the supported library api have the prefix | |
| `m4__', | |
| + Function names should be verb phrases; m4_module_get_field. | |
| + Functions which exist to be used as callbacks from API functions, and | |
| hence which likely have strange looking parameters are named with the | |
| suffix `_CB', to make it obvious why they look a little odd. | |
| + Macros which implement fast versions of functions share the | |
| same name as the function they replace, and may not evaluate | |
| parameters more than once. | |
| + Otherwise macros are in uppercase, prefixed `M4' if they are visible | |
| to the user after installation, to help the user know when to be | |
| careful about multiple evaluations of parameters. | |
| + Function names should contain the name of the module they belong to, | |
| usually immediately after the namespace prefix: m4_module_load. | |
| + Variables should not be exported (not true, but I'm working on it), | |
| but accessor functions used instead. Note the `get'/`set' part of | |
| the symbol name comes before the module part: m4_get_module_macros. | |
| + Structures come with accessor macros named <struct name>_<field | |
| name> (in upper case), to make refactoring of nested structures much | |
| easier: SYMBOL_FLAGS. | |
| + Structures are typedeffed separately, and the structure itself | |
| generally not exported unless in the `m4__' namespace to support | |
| fast accessor macros. | |
| + An opaque abstract data type (ADT) can have public and private fields: | |
| By convention public fields will have exported accessor functions (and | |
| maybe also fast macro versions of the same), and private fields will | |
| not export accessors at all. However, there should be non-exported | |
| (or at least in the `m4__' namespace) accessor functions for even the | |
| private fields of an ADT to aid possible later refactoring. | |
| * ARCHITECTURE | |
| + There are four groups of sources in subdirectories: `gnu' contains | |
| the files maintained outside of m4, as a portability layer when building | |
| the souce for non-glibc2 machines; `m4' contains the functionality for | |
| libm4 and enables the user to write modules; `modules' implements the | |
| builtin macros for the m4 binary; `src' is a small wrapper program | |
| which links libm4 and loads initial modules to implement the m4 engine. | |
| + The headers in gnu need to be managed carefully: gnulib headers | |
| can be included by other files in the same directory using `#include | |
| "file.h"', and from files in other directories with `#include | |
| <m4/file.h>'. The include path to invocations of the compiler from | |
| various Makefile.am are set to prevent the possibility of picking up | |
| an m4/file.h when the system file.h (e.g stdbool.h) is present. This, | |
| in turn means the replacement headers can live in gnulib/m4 without | |
| suffering a renaming scheme at configure time. Don't break with the | |
| `#include' convention, or the compile will go wrong in hard to debug | |
| ways on some platforms. | |
| + Low coupling. Classes (and in C, by this I mean files of functions) | |
| should not rely on a web of other classes to be useful, they should | |
| communicate with as few other classes as possible. | |
| + High cohesion. The api and caller boundaries should be well defined | |
| and adhered to; a class should do one thing only. | |
| ======================================================================== | |
| Copyright (C) 2003, 2006, 2010, 2013-2014, 2017 Free Software | |
| Foundation, Inc. | |
| Permission is granted to copy, distribute and/or modify this document | |
| under the terms of the GNU Free Documentation License, Version 1.3 or | |
| any later version published by the Free Software Foundation; with no | |
| Invariant Sections, with no Front-Cover Texts, and with no Back-Cover | |
| Texts. A copy of the license is included in the ``GNU Free | |
| Documentation License'' file as part of this distribution. |