| 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: |
| |
| * 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 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.2 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. |
