Fossil SCM

Improvements to the coding-style guidelines from Johan Kuuse.

drh 2017-11-22 19:01 trunk

Commit 49cde9fcaf1506e4b0e6aeec713b5781c61a2032c5c96341ab6fe56dc49fbcc0

Parent 51cf75088cb5809…

1 file changed +74 -43

M www/style.wiki

+74 -43

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

	--- www/style.wiki
	+++ www/style.wiki
	@@ -1,63 +1,89 @@
1	<title>Coding Style</title>
2
3	Fossil source code should following the style guidelines below.
4
5	<b>General points</b>:
6
7	10. No line of code exceeds 80 characters in length. (Occasional

8	exceptions are made for HTML text on @-lines.)
9
10	11. There are no tab characters.


11
12	12. Line terminators are \n only. Do not use a \r\n line terminator.
13
14	13. 2-space indentation is used. Remember: No tabs.
15
16	14. Comments contain no spelling or grammatical errors. (Abbreviations
17	and sentence fragments are acceptable when trying to fit a comment
18	on a single line as long as the meaning is clear.)
19
20	15. The tone of comments is professional and courteous. Comments
21	contain no profanity, obscenity, or innuendo.
22
23	16. All C-code conforms to ANSI C-89.

















24
25	17. All comments and identifiers are in English.
26
27	18. The program is single-threaded. Do not use threads.
28	(One exception to this is the HTTP server implementation for Windows,
29	which we do not know how to implement without the use of threads.)
30



31
32	<b>C preprocessor macros</b>:
33
34	20. The purpose of every preprocessor macros is clearly explained in a
35	comment associated with its definition.
36
37	21. Every preprocessor macro is used at least once.
38
39	22. The names of preprocessor macros clearly reflect their use.
40
41	23. Assumptions about the relative values of related macros are
42	verified by asserts. Example: <tt>assert(READ_LOCK+1==WRITE_LOCK);</tt>
43


44
45	<b>Function header comments</b>:
46
47	30. Every function has a header comment describing the purpose and use

48	of the function.
49
50	31. Function header comment defines the behavior of the function in
51	sufficient detail to allow the function to be re-implemented from
52	scratch without reference to the original code.
53
54	32. Functions that perform dynamic memory allocation (either directly
55	or indirectly via subfunctions) say so in their header comments.
56


57
58	<b>Function bodies</b>:
59
60	<ol>
61	<li value=40> The name of a function clearly reflects its purpose.
62
63	<li> Automatic variables are small, not large objects or arrays. Avoid
	@@ -78,44 +104,49 @@
78	</ol>
79
80	</ol>
81
82
83	<b>Class (struct) declarations</b>:
84
85	50. The purpose and use of every class (a.k.a. structure) is clearly defined

86	in the header comment of its declaration.
87
88	51. The purpose and use of every class member is clearly defined either
89	in the header comment of the class declaration or when the member is
90	declared or both.
91
92	52. The names of class members clearly reflect their use.




93
94	53. Invariants for classes are clearly defined.
95
96	<b>Variables and class instances</b>:
97
98	60. The purpose and use of every variable is defined by a comment at the
99	variable definition.
100
101	61. The names of variables clearly reflect their use.
102
103	62. Related variables have related names. (ex: aSavepoint and nSavepoint.)
104
105	63. Variables have minimum practical scope.
106
107	64. Automatic variables are small, not large objects or arrays.
108
109	65. Constants are "const".
110
111	66. Invariants on variables or groups of variables are defined and
112	tested by asserts.
113
114	67. When a variable that refers to the same value is used within
115	multiple scopes, the same name is used in all cases.
116
117	68. When variables refer to different values, different names are used
118	even when the names are in different scopes.
119
120	69. Variable names with wide scope are sufficiently distinctive to allow
121	searching for them using grep.

122

	--- www/style.wiki
	+++ www/style.wiki
	@@ -1,63 +1,89 @@
1	<title>Coding Style</title>
2
3	Fossil source code should following the style guidelines below.
4
5	<b>1. General points</b>:
6
7	<ol>
8	<li value=10> No line of code exceeds 80 characters in length. (Occasional
9	exceptions are made for HTML text on @-lines.)
10
11	<li> There are no tab characters.
12
13	<li> Line terminators are \n only. Do not use a \r\n line terminator.
14
15	<li> 2-space indentation is used. Remember: No tabs.
16
17	<li> Comments contain no spelling or grammatical errors. (Abbreviations


18	and sentence fragments are acceptable when trying to fit a comment
19	on a single line as long as the meaning is clear.)
20
21	<li> The tone of comments is professional and courteous. Comments
22	contain no profanity, obscenity, or innuendo.
23
24	<li> All C-code conforms to ANSI C-89.
25	Three well-defined existing exceptions are:
26	<ol type="a">
27
28	<li> -Wno-overlength-strings: The Fossil build system converts (some of the) source code comments
29	into strings, which may exceed the 509 character limit defined by ANSI.
30	(example: bld/page_index.h)
31
32	<li> -Wno-long-long: Fossil uses the 'long long' integer type, which is not strictly ANSI C-89 (defined in C99).
33	The use of 'long long' resolves many problems with 64-bit arithmetics, especially on 32-bit machines.
34	(http_ssl.c, sha3.c, shell.c, util.c)
35
36	<li> alloca(): By default, sqlite3.c is compiled with the -DSQLITE_USE_ALLOCA flag to use the alloca() function.
37	alloca() is not considered ANSI C, and normally not recommended due to portability issues, but
38	performance and/or memory consumption improvement may be a stronger argument in favor of its usage.
39	(sqlite3.c)
40
41	</ol>
42
43	<li> All comments and identifiers are in English.
44
45	<li> The program is single-threaded. Do not use threads.
46	(One exception to this is the HTTP server implementation for Windows,
47	which we do not know how to implement without the use of threads.)
48
49	</ol>
50
51	<b>2. C preprocessor macros</b>:
52
53	<ol>
54
55	<li value=20> The purpose of every preprocessor macros is clearly explained in a
56	comment associated with its definition.
57
58	<li> Every preprocessor macro is used at least once.
59
60	<li> The names of preprocessor macros clearly reflect their use.
61
62	<li> Assumptions about the relative values of related macros are
63	verified by asserts. Example: <tt>assert(READ_LOCK+1==WRITE_LOCK);</tt>
64
65	</ol>
66
67
68	<b>3. Function header comments</b>:
69
70	<ol>
71	<li value=30> Every function has a header comment describing the purpose and use
72	of the function.
73
74	<li> Function header comment defines the behavior of the function in
75	sufficient detail to allow the function to be re-implemented from
76	scratch without reference to the original code.
77
78	<li> Functions that perform dynamic memory allocation (either directly
79	or indirectly via subfunctions) say so in their header comments.
80
81	</ol>
82
83
84	<b>4. Function bodies</b>:
85
86	<ol>
87	<li value=40> The name of a function clearly reflects its purpose.
88
89	<li> Automatic variables are small, not large objects or arrays. Avoid
	@@ -78,44 +104,49 @@
104	</ol>
105
106	</ol>
107
108
109	<b>5. Class (struct) declarations</b>:
110
111	<ol>
112	<li value=50> The purpose and use of every class (a.k.a. structure) is clearly defined
113	in the header comment of its declaration.
114
115	<li> The purpose and use of every class member is clearly defined either
116	in the header comment of the class declaration or when the member is
117	declared or both.
118
119	<li> The names of class members clearly reflect their use.
120
121	<li> Invariants for classes are clearly defined.
122
123	</ol>
124
125	<b>6. Variables and class instances</b>:
126
127	<ol>
128	<li value=60> The purpose and use of every variable is defined by a comment at the

129	variable definition.
130
131	<li> The names of variables clearly reflect their use.
132
133	<li> Related variables have related names. (ex: aSavepoint and nSavepoint.)
134
135	<li> Variables have minimum practical scope.
136
137	<li> Automatic variables are small, not large objects or arrays.
138
139	<li> Constants are "const".
140
141	<li> Invariants on variables or groups of variables are defined and
142	tested by asserts.
143
144	<li> When a variable that refers to the same value is used within
145	multiple scopes, the same name is used in all cases.
146
147	<li> When variables refer to different values, different names are used
148	even when the names are in different scopes.
149
150	<li> Variable names with wide scope are sufficiently distinctive to allow
151	searching for them using grep.
152	</ol>
153

Fossil SCM

Keyboard Shortcuts