Fossil

Check-in [49cde9fc]
Login

Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

Overview
Comment:Improvements to the coding-style guidelines from Johan Kuuse.
Downloads: Tarball | ZIP archive | SQL archive
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA3-256: 49cde9fcaf1506e4b0e6aeec713b5781c61a2032c5c96341ab6fe56dc49fbcc0
User & Date: drh 2017-11-22 19:01:55
Context
2017-11-24
20:10
Provide a configuration option that can move the hash in a timeline before the comment, after the comment, or into the details, and can omit the details span. check-in: 4102f608 user: drh tags: trunk
14:19
Give greater emphasis to the check-in comment on timeline displays. Move the check-in hash into the details section at the end of each entry. check-in: 4438e68d user: drh tags: timeline-improvements
2017-11-22
19:01
Improvements to the coding-style guidelines from Johan Kuuse. check-in: 49cde9fc user: drh tags: trunk
2017-11-18
19:58
Improvements to the "Fossil Build Process" documentation, with improved comments in related source files. No changes to real code. check-in: 51cf7508 user: drh tags: trunk
Changes
Hide Diffs Unified Diffs Ignore Whitespace Patch

Changes to www/style.wiki.

1
2
3
4
5
6

7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23


24















25
26
27
28
29
30

31
32
33


34
35
36
37
38
39
40
41
42
43

44

45
46

47
48
49
50
51
52
53
54
55
56

57

58
59
60
61
62
63
64
65
..
76
77
78
79
80
81
82
83
84

85
86
87
88
89
90
91
92
93
94
95


96
97

98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121

<title>Coding Style</title>

Fossil source code should following the style guidelines below.

<b>General points</b>:


  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.

  12.  Line terminators are \n only.  Do not use a \r\n line terminator.

  13.  2-space indentation is used.  Remember:  No tabs.

  14.  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
       contain no profanity, obscenity, or innuendo.

  16.  All C-code conforms to ANSI C-89.


















  17.  All comments and identifiers are in English.

  18.  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.)



<b>C preprocessor macros</b>:



  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.

  22.  The names of preprocessor macros clearly reflect their use.

  23.  Assumptions about the relative values of related macros are
       verified by asserts.  Example: <tt>assert(READ_LOCK+1==WRITE_LOCK);</tt>




<b>Function header comments</b>:


  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
       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
       or indirectly via subfunctions) say so in their header comments.




<b>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>  Invariants are identified by asserts.
    </ol>

</ol>


<b>Class (struct) declarations</b>:


  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
     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.

  53.  Invariants for classes are clearly defined.



<b>Variables and class instances</b>:


  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.

  62.  Related variables have related names. (ex: aSavepoint and nSavepoint.)

  63.  Variables have minimum practical scope.

  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
     tested by asserts.

  67.  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
     even when the names are in different scopes.

  69.  Variable names with wide scope are sufficiently distinctive to allow
     searching for them using grep.





|

>
|


|

|

|

|



|


|
>
>

>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|

|



>

|

>
>
|


|

|

|


>

>
|

>
|


|



|


>

>
|







 







|

>
|


|



|

|

>
>
|

>
|


|

|

|

|

|

|


|


|


|

>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
...
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
<title>Coding Style</title>

Fossil source code should following the style guidelines below.

<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>  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>