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
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
|
/*====================================================================*
- Copyright (C) 2001 Leptonica. All rights reserved.
-
- Redistribution and use in source and binary forms, with or without
- modification, are permitted provided that the following conditions
- are met:
- 1. Redistributions of source code must retain the above copyright
- notice, this list of conditions and the following disclaimer.
- 2. Redistributions in binary form must reproduce the above
- copyright notice, this list of conditions and the following
- disclaimer in the documentation and/or other materials
- provided with the distribution.
-
- THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
- ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
- LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
- A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL ANY
- CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
- EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
- PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
- PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY
- OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
- NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
- SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
*====================================================================*/
style-guide.txt
10 May 2019
This is not a complete guide to the coding style in leptonica.
It covers most of the typographic issues and the most frequent
coding patterns, such as how to check input args to functions.
In general, you need to look at existing code to verify that your
code meets the style guidelines. And if you find any aberrant code,
please let me know!
The C code in leptonica follows these conventions:
(1) ANSI C, with no exceptions
(a) C-style comments only: /* */
(b) Variables are declared at the beginning of a function.
[This is more strict than ANSI C, which only requires declarations
to be at the beginning of a scope delineated by braces.]
(c) Use typedefs for structs like Pix; e.g.,
function(PIX *pixs)
Do not do this (omitting the 'struct' keyword); it is valid C++,
but not C:
function(Pix *pixs)
(2) Formatting
(a) White space: 4 space indentation. No tabs, ever. No trailing spaces.
(b) The code is set up to work with doxygen. Function headers are in
this format:
/*!
* \brief pixSelectByAreaFraction()
*
* \param[in] pixs 1 bpp
* \param[in] thresh threshold ratio of fg pixels to (w * h)
* \param[in] connectivity 4 or 8
* \param[in] type L_SELECT_IF_LT, L_SELECT_IF_GT,
* L_SELECT_IF_LTE, L_SELECT_IF_GTE
* \param[out] pchanged [optional] 1 if changed; 0 if clone returned
* \return pixd, or NULL on error
*
* <pre>
* Notes:
* (1) The args specify constraints on the amount of foreground
* coverage of the components that are kept.
* ....
* </pre>
*/
(c) Function definition has return value on separate line and starting
brace on separate line.
PIX *
function(...)
{
(d) Function arguments and local variables line up vertically;
allow at least 2 spaces between type and variable name (including '*')
function(PIX *pixs,
l_int32 factor,
l_float32 *pave)
{
char buf[BUF_SIZE];
l_int32 w, h, d;
l_float32 *vect;
(e) Braces are placed like this for 'if', 'while', 'do':
if (...) {
...
} else if (...) {
...
}
The exceptions are for the beginning of a function and for the switch:
switch (x)
{
case 1:
...
...
}
Braces are required if any of the clauses have more than one statement:
if (...) {
x = 0;
} else {
x++;
y = 3.0 * x;
}
(f) Section headers should look like this:
/*----------------------------------------------------------------------*
* Statistics in an arbitrary rectangle *
*----------------------------------------------------------------------*/
(g) Major inline comments (starting a section) should be indented
4 extra spaces and start with a capital. Multiple line comments
should be formatted like this:
/* If w and h not input, determine the minimum size required
* to contain the origin and all c.c. */
(h) Minor inline comments (e.g., at the end of a line) should have
2 spaces and no leading capital; e.g.
if (i && ((i % ncols) == 0)) { /* start new row */
(3) Naming
(a) Function names begin with lower case and successive words have
the first letter capitalized; e.g., boxIntersects().
(b) The first word in the function name is the name of the primary
input data structure (if there is one); otherwise it can
name the output data structure (if there is one).
(c) Variable names are as short as possible, without causing confusion.
(d) Pointers to data structures are typically named by the type of
struct, without a leading 'p'; e.g., pixt, boxt.
(e) When ptrs are input to a function, in order to return a value,
if the local name would be 'ave', the pointer is 'pave'.
(f) Preprocessor variables and enums are named all caps,
with '_' between parts.
(g) Static constants defined in a file should have the first letter of
each word capitalized. (There are also some that are formatted
like enums, with all caps and '_' between parts.)
(h) There are very few globals in the library. Of these, there
are just a handful of static globals that can be changed.
Const globals are named with each word beginning with a capital; e.g.,
ImageFileFormatExtensions[]
Static globals that can be changed are named like preprocessor
variables, except they are prepended by 'var_'; e.g.,
var_PNG_WRITE_ALPHA
Functions that set these static globals are named with a
pre-pended 'l_'; e.g.,
l_pngSetWriteAlpha()
(i) Where there may be issues with namespace collisions with other
libraries, function names can be prepended with 'l_'; e.g.,
l_amapInsert()
(4) Arg checking
Both number values and ptrs can be returned in function arguments.
The following applies equally to both types, and happens at the
beginning of the function. We distinguish between returned entities
that are optional and required. The following sequence of tests
and initializations guarantees that no uninitialized arguments
are returned:
(a) First, all optional values are initialized if possible:
if (pboxa) *pboxa = NULL; // Boxa **pboxa is optional
(b) Second, if there is more than 1 required value, each is
initialized if possible:
if (pnar) *pnar = NULL; // Numa **pnar is required
if (pnag) *pnag = NULL; // Numa **pnag is required
Then all required arguments are tested in arbitrary order.
But if there is exactly 1 required value, it can be checked
and initialized if possible:
if (!ppixd)
return ERROR_INT("&pixd not defined, procName, 1);
*ppixd = NULL;
(5) Miscellaneous
(a) Look around at the code after reviewing the guidelines.
(b) Return nothing on stdout.
(c) Returns to stderr should be blockable by compiler flags, such
as NO_CONSOLE_IO, and by setting message severity thresholds
both at compile and at run time. Naked fprintf(stderr, ...)
should be avoided in the library.
(d) Applications (in prog) that hand a FILE ptr to a library function,
or accept heap-allocated data from a library function, should
use special wrappers. See lept_*() functions in utils.c.
(e) Changes to existing data structures and API changes should be
avoided if possible.
(f) Accessors are typically provided for struct fields that have
extensive use.
|
