1<title>Coding Style</title>
2
3Fossil source code should following the style guidelines below.
4
5<em> The Fossil source tree includes a few files taken from external
6sources
7(examples: [https://github.com/antirez/linenoise|linenoise] and
8[http://zlib.net/|zLib])
9and 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 is compiled with the -DSQLITE_USE_ALLOCA flag to use the alloca() function.
44        alloca() is not considered ANSI C, and normally not recommended due to portability issues, but
45        performance and/or memory consumption improvement may be a stronger argument in favor of its usage.
46        (sqlite3.c)
47     </ol>
48
49  <li>  All comments and identifiers are in English.
50
51  <li>  The program is single-threaded.  Do not use threads.
52       (One exception to this is the HTTP server implementation for Windows,
53       which we do not know how to implement without the use of threads.)
54
55</ol>
56
57<b>2. C preprocessor macros</b>:
58
59<ol>
60
61  <li value=20>  The purpose of every preprocessor macros is clearly explained in a
62       comment associated with its definition.
63
64  <li>  Every preprocessor macro is used at least once.
65
66  <li>  The names of preprocessor macros clearly reflect their use.
67
68  <li>  Assumptions about the relative values of related macros are
69       verified by asserts.  Example: <tt>assert(READ_LOCK+1==WRITE_LOCK);</tt>
70
71</ol>
72
73
74<b>3. Function header comments</b>:
75
76<ol>
77  <li value=30>  Every function has a header comment describing the purpose and use
78       of the function.
79
80  <li>  Function header comment defines the behavior of the function in
81       sufficient detail to allow the function to be re-implemented from
82       scratch without reference to the original code.
83
84  <li>  Functions that perform dynamic memory allocation (either directly
85       or indirectly via subfunctions) say so in their header comments.
86
87</ol>
88
89
90<b>4. Function bodies</b>:
91
92<ol>
93  <li value=40>  The name of a function clearly reflects its purpose.
94
95  <li> Automatic variables are small, not large objects or arrays.  Avoid
96       excessive stack usage.
97
98  <li>  The check-list items for functions also apply to major subsections
99     within a function.
100
101  <li>  All code subblocks are enclosed in {...}.
102
103
104  <li> <b>assert() macros are used as follows</b>:
105    <ol type="a">
106
107  <li>  Function preconditions are clearly stated and verified by asserts.
108
109  <li>  Invariants are identified by asserts.
110    </ol>
111
112</ol>
113
114
115<b>5. Class (struct) declarations</b>:
116
117<ol>
118  <li value=50>  The purpose and use of every class (a.k.a. structure) is clearly defined
119     in the header comment of its declaration.
120
121  <li>  The purpose and use of every class member is clearly defined either
122     in the header comment of the class declaration or when the member is
123     declared or both.
124
125  <li>  The names of class members clearly reflect their use.
126
127  <li>  Invariants for classes are clearly defined.
128
129</ol>
130
131<b>6. Variables and class instances</b>:
132
133<ol>
134  <li value=60>  The purpose and use of every variable is defined by a comment at the
135     variable definition.
136
137  <li>  The names of variables clearly reflect their use.
138
139  <li>  Related variables have related names. (ex: aSavepoint and nSavepoint.)
140
141  <li>  Variables have minimum practical scope.
142
143  <li>  Automatic variables are small, not large objects or arrays.
144
145  <li>  Constants are "const".
146
147  <li>  Invariants on variables or groups of variables are defined and
148     tested by asserts.
149
150  <li>  When a variable that refers to the same value is used within
151     multiple scopes, the same name is used in all cases.
152
153  <li>  When variables refer to different values, different names are used
154     even when the names are in different scopes.
155
156  <li>  Variable names with wide scope are sufficiently distinctive to allow
157     searching for them using grep.
158</ol>
159