1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
|
Copyright (C) 2009, 2010 Peter Breitenlohner <tex-live@tug.org>
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.
|
