Fossil SCM

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

Keyboard Shortcuts

Open search /
Next entry (timeline) j
Previous entry (timeline) k
Open focused entry Enter
Show this help ?
Toggle theme Top nav button