|
1
|
<title>Coding Style</title> |
|
2
|
|
|
3
|
Fossil source code should follow the style guidelines below. |
|
4
|
|
|
5
|
<em> The Fossil source tree includes a few files taken from external |
|
6
|
sources |
|
7
|
(examples: [https://github.com/antirez/linenoise|linenoise] and |
|
8
|
[http://zlib.net/|zLib]) |
|
9
|
and this externally sourced code might not comply with these style guidelines. |
|
10
|
</em> |
|
11
|
|
|
12
|
<b>1. General points</b>: |
|
13
|
|
|
14
|
<ol> |
|
15
|
<li value=10> No line of code exceeds 80 characters in length. (Occasional |
|
16
|
exceptions are made for HTML text on @-lines.) |
|
17
|
|
|
18
|
<li> There are no tab characters. |
|
19
|
|
|
20
|
<li> Line terminators are \n only. Do not use a \r\n line terminator. |
|
21
|
|
|
22
|
<li> 2-space indentation is used. Remember: No tabs. |
|
23
|
|
|
24
|
<li> Comments contain no spelling or grammatical errors. (Abbreviations |
|
25
|
and sentence fragments are acceptable when trying to fit a comment |
|
26
|
on a single line as long as the meaning is clear.) |
|
27
|
|
|
28
|
<li> The tone of comments is professional and courteous. Comments |
|
29
|
contain no profanity, obscenity, or innuendo. |
|
30
|
|
|
31
|
<li> All C-code conforms to ANSI C-89. |
|
32
|
Three well-defined existing exceptions are: |
|
33
|
<ol type="a"> |
|
34
|
|
|
35
|
<li> -Wno-overlength-strings: The Fossil build system converts (some of the) source code comments |
|
36
|
into strings, which may exceed the 509 character limit defined by ANSI. |
|
37
|
(example: bld/page_index.h) |
|
38
|
|
|
39
|
<li> -Wno-long-long: Fossil uses the 'long long' integer type, which is not strictly ANSI C-89 (defined in C99). |
|
40
|
The use of 'long long' resolves many problems with 64-bit arithmetics, especially on 32-bit machines. |
|
41
|
(http_ssl.c, sha3.c, shell.c, util.c) |
|
42
|
|
|
43
|
<li> alloca(): By default, sqlite3.c was compiled with the -DSQLITE_USE_ALLOCA flag to use the alloca() function. |
|
44
|
This is no longer the case as of 20220119. alloca() is not considered ANSI C, and normally not |
|
45
|
recommended due to portability issues, but performance and/or memory consumption |
|
46
|
improvement may have been a stronger argument in favor of its usage. |
|
47
|
(sqlite3.c) |
|
48
|
</ol> |
|
49
|
|
|
50
|
<li> All comments and identifiers are in English. |
|
51
|
|
|
52
|
<li> The program is single-threaded. Do not use threads. |
|
53
|
(One exception to this is the HTTP server implementation for Windows, |
|
54
|
which we do not know how to implement without the use of threads.) |
|
55
|
|
|
56
|
</ol> |
|
57
|
|
|
58
|
<b>2. C preprocessor macros</b>: |
|
59
|
|
|
60
|
<ol> |
|
61
|
|
|
62
|
<li value=20> The purpose of every preprocessor macros is clearly explained in a |
|
63
|
comment associated with its definition. |
|
64
|
|
|
65
|
<li> Every preprocessor macro is used at least once. |
|
66
|
|
|
67
|
<li> The names of preprocessor macros clearly reflect their use. |
|
68
|
|
|
69
|
<li> Assumptions about the relative values of related macros are |
|
70
|
verified by asserts. Example: <tt>assert(READ_LOCK+1==WRITE_LOCK);</tt> |
|
71
|
|
|
72
|
</ol> |
|
73
|
|
|
74
|
|
|
75
|
<b>3. Function header comments</b>: |
|
76
|
|
|
77
|
<ol> |
|
78
|
<li value=30> Every function has a header comment describing the purpose and use |
|
79
|
of the function. |
|
80
|
|
|
81
|
<li> A function header comment defines the behavior of the function in |
|
82
|
sufficient detail to allow the function to be re-implemented from |
|
83
|
scratch without reference to the original code. |
|
84
|
|
|
85
|
<li> Functions that perform dynamic memory allocation (either directly |
|
86
|
or indirectly via subfunctions) say so in their header comments. |
|
87
|
|
|
88
|
</ol> |
|
89
|
|
|
90
|
|
|
91
|
<b>4. Function bodies</b>: |
|
92
|
|
|
93
|
<ol> |
|
94
|
<li value=40> The name of a function clearly reflects its purpose. |
|
95
|
|
|
96
|
<li> Automatic variables are small, not large objects or arrays. Avoid |
|
97
|
excessive stack usage. |
|
98
|
|
|
99
|
<li> The check-list items for functions also apply to major subsections |
|
100
|
within a function. |
|
101
|
|
|
102
|
<li> All code subblocks are enclosed in {...}. |
|
103
|
|
|
104
|
|
|
105
|
<li> <b>assert() macros are used as follows</b>: |
|
106
|
<ol type="a"> |
|
107
|
|
|
108
|
<li> Function preconditions are clearly stated and verified by asserts. |
|
109
|
|
|
110
|
<li> Invariants are identified by asserts. |
|
111
|
</ol> |
|
112
|
|
|
113
|
</ol> |
|
114
|
|
|
115
|
|
|
116
|
<b>5. Class (struct) declarations</b>: |
|
117
|
|
|
118
|
<ol> |
|
119
|
<li value=50> The purpose and use of every class (a.k.a. structure) is clearly defined |
|
120
|
in the header comment of its declaration. |
|
121
|
|
|
122
|
<li> The purpose and use of every class member is clearly defined either |
|
123
|
in the header comment of the class declaration or when the member is |
|
124
|
declared or both. |
|
125
|
|
|
126
|
<li> The names of class members clearly reflect their use. |
|
127
|
|
|
128
|
<li> Invariants for classes are clearly defined. |
|
129
|
|
|
130
|
</ol> |
|
131
|
|
|
132
|
<b>6. Variables and class instances</b>: |
|
133
|
|
|
134
|
<ol> |
|
135
|
<li value=60> The purpose and use of every variable is defined by a comment at the |
|
136
|
variable definition. |
|
137
|
|
|
138
|
<li> The names of variables clearly reflect their use. |
|
139
|
|
|
140
|
<li> Related variables have related names. (ex: aSavepoint and nSavepoint.) |
|
141
|
|
|
142
|
<li> Variables have minimum practical scope. |
|
143
|
|
|
144
|
<li> Automatic variables are small, not large objects or arrays. |
|
145
|
|
|
146
|
<li> Constants are "const". |
|
147
|
|
|
148
|
<li> Invariants on variables or groups of variables are defined and |
|
149
|
tested by asserts. |
|
150
|
|
|
151
|
<li> When a variable that refers to the same value is used within |
|
152
|
multiple scopes, the same name is used in all cases. |
|
153
|
|
|
154
|
<li> When variables refer to different values, different names are used |
|
155
|
even when the names are in different scopes. |
|
156
|
|
|
157
|
<li> Variable names with wide scope are sufficiently distinctive to allow |
|
158
|
searching for them using grep. |
|
159
|
</ol> |
|
160
|
|