From 4f49b16079b27d7ce633619e4cddfdf2bffbc952 Mon Sep 17 00:00:00 2001 From: cashmere Date: Fri, 4 Sep 2026 09:05:24 +0200 Subject: initial commit --- www/style.wiki | 159 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 159 insertions(+) create mode 100644 www/style.wiki (limited to 'www/style.wiki') diff --git a/www/style.wiki b/www/style.wiki new file mode 100644 index 0000000..10b009e --- /dev/null +++ b/www/style.wiki @@ -0,0 +1,159 @@ +Coding Style + +Fossil source code should follow the style guidelines below. + + 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. + + +1. General points: + +
    +
  1. No line of code exceeds 80 characters in length. (Occasional + exceptions are made for HTML text on @-lines.) + +
  2. There are no tab characters. + +
  3. Line terminators are \n only. Do not use a \r\n line terminator. + +
  4. 2-space indentation is used. Remember: No tabs. + +
  5. 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.) + +
  6. The tone of comments is professional and courteous. Comments + contain no profanity, obscenity, or innuendo. + +
  7. All C-code conforms to ANSI C-89. + Three well-defined existing exceptions are: +
      + +
    1. -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) + +
    2. -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) + +
    3. alloca(): By default, sqlite3.c was compiled with the -DSQLITE_USE_ALLOCA flag to use the alloca() function. + This is no longer the case as of 20220119. alloca() is not considered ANSI C, and normally not + recommended due to portability issues, but performance and/or memory consumption + improvement may have been a stronger argument in favor of its usage. + (sqlite3.c) +
    + +
  8. All comments and identifiers are in English. + +
  9. 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.) + +
+ +2. C preprocessor macros: + +
    + +
  1. The purpose of every preprocessor macros is clearly explained in a + comment associated with its definition. + +
  2. Every preprocessor macro is used at least once. + +
  3. The names of preprocessor macros clearly reflect their use. + +
  4. Assumptions about the relative values of related macros are + verified by asserts. Example: assert(READ_LOCK+1==WRITE_LOCK); + +
+ + +3. Function header comments: + +
    +
  1. Every function has a header comment describing the purpose and use + of the function. + +
  2. A 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. + +
  3. Functions that perform dynamic memory allocation (either directly + or indirectly via subfunctions) say so in their header comments. + +
+ + +4. Function bodies: + +
    +
  1. The name of a function clearly reflects its purpose. + +
  2. Automatic variables are small, not large objects or arrays. Avoid + excessive stack usage. + +
  3. The check-list items for functions also apply to major subsections + within a function. + +
  4. All code subblocks are enclosed in {...}. + + +
  5. assert() macros are used as follows: +
      + +
    1. Function preconditions are clearly stated and verified by asserts. + +
    2. Invariants are identified by asserts. +
    + +
+ + +5. Class (struct) declarations: + +
    +
  1. The purpose and use of every class (a.k.a. structure) is clearly defined + in the header comment of its declaration. + +
  2. 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. + +
  3. The names of class members clearly reflect their use. + +
  4. Invariants for classes are clearly defined. + +
+ +6. Variables and class instances: + +
    +
  1. The purpose and use of every variable is defined by a comment at the + variable definition. + +
  2. The names of variables clearly reflect their use. + +
  3. Related variables have related names. (ex: aSavepoint and nSavepoint.) + +
  4. Variables have minimum practical scope. + +
  5. Automatic variables are small, not large objects or arrays. + +
  6. Constants are "const". + +
  7. Invariants on variables or groups of variables are defined and + tested by asserts. + +
  8. When a variable that refers to the same value is used within + multiple scopes, the same name is used in all cases. + +
  9. When variables refer to different values, different names are used + even when the names are in different scopes. + +
  10. Variable names with wide scope are sufficiently distinctive to allow + searching for them using grep. +
-- cgit v1.3.1