Copyright (C) 2009, 2010 Peter Breitenlohner You may freely use, modify and/or distribute this file. TeX Live (TL) coding rules ========================== Ideally, building all of TL with '--enable-compiler-warnings=max' should produce no (gcc) compiler warnings at all. In spite of considerable efforts into that direction we are still far from that goal and there are reasons that we may never fully reach it. Below are some rules about declarations (of functions and variables) and the use of `const'. These rules should be applied to all parts of the TL tree, except in some of those maintained independently. 1. Declarations =============== 1.1. ANSI C function prototypes and definitions ----------------------------------------------- The TL build system no longer supports pre-ANSI C compilers. Thus all function prototypes and definitions must conform to the ANSI C standard (including `void' in the declaration of functions that take no parameters). 1.2. Static ----------- Functions used in only one file must be declared `static'; no prototype is required except as forward declaration. 1.3. Extern ----------- Functions used in several files require (extern) prototypes to be provided by a header files. That header must be included in the file defining the function and in all files using that function -- this is the only way to guarantee consistency between definition and use of functions. No more `extern's sprinkled throughout the C code (with or without comment where that function is defined). 1.4. Variables -------------- The declaration of global variables should follow analogous rules, they should either be static or declared extern in a header and instatiated in exectly one file. 2. Const ======== 2.1. Function parameters ------------------------ Ideally, a function parameter not modified by the function should be declared as const. This is important in particiular for strings (`char *') because frequently string literals are used as actual arguments. Note, however, that a `char **' value is not assignment compatible with a `const char **' variable. Getting all `const's right often is quite involved but usually can be done. There are, however, a few notable exceptions: the X11 headers are full of declarations that ought to use const but do not and the same is true to some extent for zlib and freetype2. 2.2. What must be avoided ------------------------- The compiler warnings `assignment/initialization/passing arg/return discards qualifiers...' must be avoided under all circumstances, except when caused by X11 headers/macros or third party code. 2.3. What should be avoided --------------------------- A type cast, e.g., from `const char *' to `char *' doesn't solve any problems, depending on warning options it only may hide them. Therefore such casts should be avoided whenever possible but some such casts may be unavoidable.