2006-09-21 Mark Rowe <opendarwin.org@bdash.net.nz>
[WebKit-https.git] / WebKitSite / coding / coding-style.html
1 <?php 
2     $title="WebKit Coding Style Guidelines";
3     include("../header.inc"); 
4 ?>
5
6
7 <h2>WebKit Coding Style Guidelines</h2>
8 <h3>Indenting</h3>
9
10 <ol>
11 <li> Use spaces to indent. Tabs should not appear in code files (with the exception of files that require tabs, e.g. Makefiles).
12      We have a Subversion pre-commit script that enforces this rule for most
13      source files, preventing commits of files that don't follow this rule.
14 </li>
15 <li> The indent size is 4 spaces.</li>
16 <li> Code editors should be configured to expand tabs that you type to 4 spaces.</li>
17 </ol>
18
19 <h3>Braces</h3>
20 <ol>
21 <li> Function definitions &mdash; open and close braces should be on lines by themselves. Do not put the open brace on the same line as the function signature. For example:<br>
22
23 <h4 style="color: #008000 !important !important">Right:</h4>
24 <pre style="background-color: #F2F2F2">
25 void foo()
26 {
27     // do stuff
28 }
29 </pre>
30
31 <h4 style="color: #ff0000 !important">Wrong:</h4>
32 <pre style="background-color: #F2F2F2">
33 void foo() {
34     // do stuff
35 }
36 </pre>
37 </li>
38 <li> Other braces, including for, while, do, switch statements and class definitions &mdash; the open brace should go on the same line as the as the control structure.<br>
39
40 <h4 style="color: #008000 !important">Right:</h4>
41 <pre style="background-color: #F2F2F2">
42 for (int i = 0; i < 10; i++) {
43     // do stuff
44 }
45 </pre>
46
47 <h4 style="color: #ff0000 !important">Wrong:</h4>
48 <pre style="background-color: #F2F2F2">
49 for (int i = 0; i < 10; i++)
50 {
51     // do stuff
52 }
53 </pre>
54 <li> If/else statements &mdash; as above, but if there is an else clause, the close brace should go on the same line as the else.
55      Also, one-line if or else clauses should not get braces.<br>
56 <h4 style="color: #008000 !important">Right:</h4>
57 <pre style="background-color: #F2F2F2">
58 if (timeToGetCoffee) {
59     buyCoffee(&#038;coffee);
60     chugIt(coffee);
61 } else if (timeToGoHome)
62     // comment on else case
63     outtaHere = true;
64 </pre>
65
66 <h4 style="color: #ff0000 !important">Wrong:</h4>
67 <pre style="background-color: #F2F2F2">
68 if (timeToGetCoffee)
69 {
70     buyCoffee(&#038;coffee);
71     chugIt(coffee);
72 // comment on else case
73 } else if (timeToGoHome)
74 {
75     outtaHere = true;
76 }
77     
78 if (timeToGetCoffee) {
79 }
80 else
81     
82 // comment on else case
83     
84 if (timeToGoHome)
85     outtaHere = true;
86 </pre>
87 </li>
88 </ol>
89
90 <h3>Parentheses</h3>
91 <ol>
92 <li>Function declarations and calls &mdash; do not use any spaces between the name and the open paren, inside the parentheses, or before commas that separate arguments.
93     Do use a single space after commas that separate arguments.<br>
94
95 <h4 style="color: #008000 !important">Right:</h4>
96 <pre style="background-color: #F2F2F2">
97 int myFunction(int arg1, float arg2);
98
99 void noArgFunction(); // for C++ or Objective-C++
100
101 void noArgFunction(void); // for C or Objective-C
102 </pre>
103
104 <h4 style="color: #ff0000 !important">Wrong:</h4>
105 <pre style="background-color: #F2F2F2">
106 int myFunction (int arg1, float arg2);
107
108 int myFunction( int arg1 , float arg2 );
109
110 void noArgFunction ();
111 </pre>
112 </li>
113
114 <li>Control structures, such as if, while, do and switch &mdash; use a single space before the open paren, but no spaces inside the parentheses.
115
116 </li>
117 </ol>
118
119 <h3>Null, false and 0</h3>
120 <ol>
121 <li>In C++, the null pointer value should be written as <code>0</code>. In C it should be written as <code>NULL</code>. In Objective-C, it should be written as <code>nil</code> if it is being used as a null pointer of type <code>id</code> or another ObjC object type, otherwise <code>NULL</code>.</li>
122 <li>True and false values of type <code>bool</code> (common in C and C++), or just generic true/false values, should be written as <code>true</code> and <code>false</code>. Values of the Objective-C <code>BOOL</code> type should be written as <code>YES</code> and <code>NO</code>.</li>
123 <li>Tests for null pointers, false values and 0 values should all be done directly, not through an inqueality or equality comparison.<br>
124
125 <h4 style="color: #008000 !important">Right:</h4>
126 <pre style="background-color: #F2F2F2">
127     
128 // test for true
129 if (foo->isSomething()) {
130     // code
131 }
132     
133 // test for false
134 if (!foo->isSomething()) {
135     // code
136 }
137     
138 // test for non-null
139 if (ptr) {
140    // code
141 }
142     
143 // test for null
144 if (!ptr) {
145    // code
146 }
147     
148 // test for nonzero
149 if (count) {
150     // code
151 }
152     
153 // test for zero
154 if (!count) {
155     // code
156 }
157 </pre>
158
159 <h4 style="color: #ff0000 !important">Wrong:</h4>
160 <pre style="background-color: #F2F2F2">
161 if (foo->isSomething() == true) {
162     // code
163 }
164     
165 if (foo->isSomething() != false) {
166     // code
167 }
168     
169 if (p == NULL) {
170     // code
171 }
172     
173 if (nil != p) {
174     // code
175 }
176     
177 if (count == 0) {
178     // code
179 }
180 </pre>
181 </li>
182 </ol>
183
184 <h3>Names</h3>
185 <ol>
186 <li>General Rule: With very few exceptions, prefer embedded capitals instead of underscores for class, function and variable names.</li>
187 <li>C++ and Objective-C classes, interfaces and protocols, and other type names &mdash; these names should start with a capital letter and use InterCaps.<br>
188
189 <h4 style="color: #008000 !important">Right:</h4>
190 <pre style="background-color: #F2F2F2">
191 class MyImportantClass;
192 </pre>
193
194 <h4 style="color: #ff0000 !important">Wrong:</h4>
195 <pre style="background-color: #F2F2F2">
196 class My_important_class;
197     
198 class myImportantClass;
199 </pre>
200 </li>
201
202 <li>Local variables should use interCaps, but the first word should start with a lowercase letter, like this:<br>
203
204 <h4 style="color: #008000 !important">Right:</h4>
205 <pre style="background-color: #F2F2F2">
206 int myInt;
207 </pre>
208
209 <h4 style="color: #ff0000 !important">Wrong:</h4>
210 <pre style="background-color: #F2F2F2">
211 int MyInt;
212     
213 int my_int;
214 </pre>
215 </li>
216
217 <li>Free function names in C++ should follow the same naming conventions as local variables. Most functions should be named to sound like verb phrases, like &#8220;openDoor&#8221; or &#8220;walkAroundTheBlock&#8221;. (getters, setters, predicates?)</li>
218
219 <li>C++ data members should be named like local variables, but with a prefix of m_.</li>
220 <li>C++ member functions should follow the same naming convention as free functions.</li>
221 <li>Objective-C methods should follow the usual Cocoa naming style &mdash;
222 they should read like a phrase or sentence and each piece of the selector should start with a lowercase letter and use intercaps.</li>
223 <li>Objective-C instance variables should be named like local variables but starting with an underscore.</li>
224 <li>Enum members should user InterCaps with an initial capital letter.</li>
225 <li>#defined constants should use all uppercase names with words separated by underscores.</li>
226 <li> Macros that expand to function calls or other non-constant computation: these should be named like functions, and should have parentheses at the end, even if they take no arguments (with the exception of some special macros like ASSERT). Note that usually it is preferrable to use an inline function in such cases instead of a macro.<br>
227
228 <h4 style="color: #008000 !important">Right:</h4>
229 <pre style="background-color: #F2F2F2">
230 #define WBStopButtonTitle() \
231         NSLocalizedString(@\"Stop\", @\"Stop button title\")
232 </pre>
233
234 <h4 style="color: #ff0000 !important">Wrong:</h4>
235 <pre style="background-color: #F2F2F2">
236 #define WB_STOP_BUTTON_TITLE \
237         NSLocalizedString(@\"Stop\", @\"Stop button\")
238
239 #define WBStopButtontitle \
240         NSLocalizedString(@\"Stop\", @\"Stop button\")
241 </pre>
242 </li>
243
244 <li> Acronyms in names: If an identifier includes an acronym, make the acronym all-uppercase
245      or all-lowercase, depending on whether a word in that position would be capitalized or not.<br>
246
247 <h4 style="color: #008000 !important">Right:</h4>
248 <pre style="background-color: #F2F2F2">
249 urlVariable
250 myURLAccessor:
251 </pre>
252
253 <h4 style="color: #ff0000 !important">Wrong:</h4>
254 <pre style="background-color: #F2F2F2">
255 uRLVariable
256 myUrlAccessor:
257 </pre>
258 </li>
259 </ol>
260
261 <h3>Other Punctuation</h3>
262
263 <ol>
264
265 <li>Pointer and reference types in C++ code &mdash; Both pointer types and reference types
266 should be written with no space between the type name and the * or &amp;.
267
268 <li>Pointer types in non-C++ code &mdash; Pointer types should be written with a space between the
269 type and the * (so the * is adjacent to the following identifier if any).
270
271 </ol>
272
273 <h3>Include Statements</h3>
274
275 <ol>
276
277 <li>All files must #include "config.h" first.
278
279 <li>All files must #include the primary header second, just after "config.h".
280 So for example, Node.cpp should include Node.h first, before other files.
281 This guarantees that each header's completeness is tested, to make sure it
282 can be compiled without requiring any other header files be included first.
283
284 <li>Other #include statements should be in sorted order (case sensitive, as
285 done by the command-line sort tool or the Xcode sort selection command).
286 Don't bother to organize them in a logical order.
287
288 </ol>
289
290 <?php
291     include("../footer.inc");
292 ?>