Hi,
A minor patch for the enumeration in www/style.wiki.
Included a proposal for a few comments about ANSI C-89.
Best regards,
Johan
Index: www/style.wiki
==================================================================
--- www/style.wiki
+++ www/style.wiki
@@ -1,63 +1,89 @@
<title>Coding Style</title>
Fossil source code should following the style guidelines below.
-<b>General points</b>:
+<b>1. General points</b>:
- 10. No line of code exceeds 80 characters in length. (Occasional
+<ol>
+ <li value=10> No line of code exceeds 80 characters in length.
(Occasional
exceptions are made for HTML text on @-lines.)
- 11. There are no tab characters.
+ <li> There are no tab characters.
- 12. Line terminators are \n only. Do not use a \r\n line terminator.
+ <li> Line terminators are \n only. Do not use a \r\n line terminator.
- 13. 2-space indentation is used. Remember: No tabs.
+ <li> 2-space indentation is used. Remember: No tabs.
- 14. Comments contain no spelling or grammatical errors. (Abbreviations
+ <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.)
- 15. The tone of comments is professional and courteous. Comments
+ <li> The tone of comments is professional and courteous. Comments
contain no profanity, obscenity, or innuendo.
- 16. All C-code conforms to ANSI C-89.
+ <li> All C-code conforms to ANSI C-89.
+ Three well-defined existing exceptions are:
+ <ol type="a">
- 17. All comments and identifiers are in English.
+ <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)
- 18. The program is single-threaded. Do not use threads.
+ <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>C preprocessor macros</b>:
+<b>2. C preprocessor macros</b>:
- 20. The purpose of every preprocessor macros is clearly explained in a
+<ol>
+
+ <li value=20> The purpose of every preprocessor macros is clearly
explained in a
comment associated with its definition.
- 21. Every preprocessor macro is used at least once.
+ <li> Every preprocessor macro is used at least once.
- 22. The names of preprocessor macros clearly reflect their use.
+ <li> The names of preprocessor macros clearly reflect their use.
- 23. Assumptions about the relative values of related macros are
+ <li> Assumptions about the relative values of related macros are
verified by asserts. Example:
<tt>assert(READ_LOCK+1==WRITE_LOCK);</tt>
+</ol>
-<b>Function header comments</b>:
- 30. Every function has a header comment describing the purpose and use
+<b>3. Function header comments</b>:
+
+<ol>
+ <li value=30> Every function has a header comment describing the
purpose and use
of the function.
- 31. Function header comment defines the behavior of the function in
+ <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.
- 32. Functions that perform dynamic memory allocation (either directly
+ <li> Functions that perform dynamic memory allocation (either directly
or indirectly via subfunctions) say so in their header comments.
+</ol>
-<b>Function bodies</b>:
+
+<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
@@ -78,44 +104,49 @@
</ol>
</ol>
-<b>Class (struct) declarations</b>:
+<b>5. Class (struct) declarations</b>:
- 50. The purpose and use of every class (a.k.a. structure) is clearly
defined
+<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.
- 51. The purpose and use of every class member is clearly defined either
+ <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.
- 52. The names of class members clearly reflect their use.
+ <li> The names of class members clearly reflect their use.
+
+ <li> Invariants for classes are clearly defined.
+
+</ol>
- 53. Invariants for classes are clearly defined.
+<b>6. Variables and class instances</b>:
-<b>Variables and class instances</b>:
-
- 60. The purpose and use of every variable is defined by a comment at the
+<ol>
+ <li value=60> The purpose and use of every variable is defined by a
comment at the
variable definition.
- 61. The names of variables clearly reflect their use.
+ <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.
- 62. Related variables have related names. (ex: aSavepoint and
nSavepoint.)
+ <li> Automatic variables are small, not large objects or arrays.
- 63. Variables have minimum practical scope.
+ <li> Constants are "const".
- 64. Automatic variables are small, not large objects or arrays.
-
- 65. Constants are "const".
-
- 66. Invariants on variables or groups of variables are defined and
+ <li> Invariants on variables or groups of variables are defined and
tested by asserts.
- 67. When a variable that refers to the same value is used within
+ <li> When a variable that refers to the same value is used within
multiple scopes, the same name is used in all cases.
- 68. When variables refer to different values, different names are used
+ <li> When variables refer to different values, different names are used
even when the names are in different scopes.
- 69. Variable names with wide scope are sufficiently distinctive to allow
+ <li> Variable names with wide scope are sufficiently distinctive to
allow
searching for them using grep.
+</ol>
_______________________________________________
fossil-dev mailing list
fossil-dev@mailinglists.sqlite.org
http://mailinglists.sqlite.org/cgi-bin/mailman/listinfo/fossil-dev
