<title>Coding Style</title>
Fossil source code should following the style guidelines below.
<em> The Fossil source tree includes a few files taken from external
sources
(examples: [https://github.com/antirez/linenoise|linenoise] and
[http://zlib.net/|zLib])
and this externally sourced code might not comply with these style guidelines.
</em>
<b>1. General points</b>:
<ol>
<li value=10> No line of code exceeds 80 characters in length. (Occasional
exceptions are made for HTML text on @-lines.)
<li> There are no tab characters.
<li> Line terminators are \n only. Do not use a \r\n line terminator.
<li> 2-space indentation is used. Remember: No tabs.
<li> Comments contain no spelling or grammatical errors. (Abbreviations
and sentence fragments are acceptable when trying to fit a comment
on a single line as long as the meaning is clear.)
<li> The tone of comments is professional and courteous. Comments
contain no profanity, obscenity, or innuendo.
<li> All C-code conforms to ANSI C-89.
Three well-defined existing exceptions are:
<ol type="a">
<li> -Wno-overlength-strings: The Fossil build system converts (some of the) source code comments
into strings, which may exceed the 509 character limit defined by ANSI.
(example: bld/page_index.h)
<li> -Wno-long-long: Fossil uses the 'long long' integer type, which is not strictly ANSI C-89 (defined in C99).
The use of 'long long' resolves many problems with 64-bit arithmetics, especially on 32-bit machines.
(http_ssl.c, sha3.c, shell.c, util.c)
<li> alloca(): By default, sqlite3.c is compiled with the -DSQLITE_USE_ALLOCA flag to use the alloca() function.
alloca() is not considered ANSI C, and normally not recommended due to portability issues, but
performance and/or memory consumption improvement may be a stronger argument in favor of its usage.
(sqlite3.c)
</ol>
<li> All comments and identifiers are in English.
<li> The program is single-threaded. Do not use threads.
(One exception to this is the HTTP server implementation for Windows,
which we do not know how to implement without the use of threads.)
</ol>
<b>2. C preprocessor macros</b>:
<ol>
<li value=20> The purpose of every preprocessor macros is clearly explained in a
comment associated with its definition.
<li> Every preprocessor macro is used at least once.
<li> The names of preprocessor macros clearly reflect their use.
<li> Assumptions about the relative values of related macros are
verified by asserts. Example: <tt>assert(READ_LOCK+1==WRITE_LOCK);</tt>
</ol>
<b>3. Function header comments</b>:
<ol>
<li value=30> Every function has a header comment describing the purpose and use
of the function.
<li> Function header comment defines the behavior of the function in
sufficient detail to allow the function to be re-implemented from
scratch without reference to the original code.
<li> Functions that perform dynamic memory allocation (either directly
or indirectly via subfunctions) say so in their header comments.
</ol>
<b>4. Function bodies</b>:
<ol>
<li value=40> The name of a function clearly reflects its purpose.
<li> Automatic variables are small, not large objects or arrays. Avoid
excessive stack usage.
<li> The check-list items for functions also apply to major subsections
within a function.
<li> All code subblocks are enclosed in {...}.
<li> <b>assert() macros are used as follows</b>:
<ol type="a">
<li> Function preconditions are clearly stated and verified by asserts.
<li> Invariants are identified by asserts.
</ol>
</ol>
<b>5. Class (struct) declarations</b>:
<ol>
<li value=50> The purpose and use of every class (a.k.a. structure) is clearly defined
in the header comment of its declaration.
<li> The purpose and use of every class member is clearly defined either
in the header comment of the class declaration or when the member is
declared or both.
<li> The names of class members clearly reflect their use.
<li> Invariants for classes are clearly defined.
</ol>
<b>6. Variables and class instances</b>:
<ol>
<li value=60> The purpose and use of every variable is defined by a comment at the
variable definition.
<li> The names of variables clearly reflect their use.
<li> Related variables have related names. (ex: aSavepoint and nSavepoint.)
<li> Variables have minimum practical scope.
<li> Automatic variables are small, not large objects or arrays.
<li> Constants are "const".
<li> Invariants on variables or groups of variables are defined and
tested by asserts.
<li> When a variable that refers to the same value is used within
multiple scopes, the same name is used in all cases.
<li> When variables refer to different values, different names are used
even when the names are in different scopes.
<li> Variable names with wide scope are sufficiently distinctive to allow
searching for them using grep.
</ol>