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