Get the Windows bots closer to green
[WebKit-https.git] / WebKitSite / coding / coding-style.html
1 <?php 
2     $title="WebKit Coding Style Guidelines";
3     include("../header.inc"); 
4 ?>
5
6 <style type="text/css">
7 pre .code {
8    background-color: #F2F2F2;
9 }
10
11 .right {
12   color: #080 !important;
13 }
14
15 .wrong {
16   color: #f00 !important;
17 }
18 </style>
19
20
21 <h2>WebKit Coding Style Guidelines</h2>
22 <h3>Indentation</h3>
23
24 <ol>
25 <li> Use spaces, not tabs. Tabs should only appear in files that require them for semantic meaning, like Makefiles.
26 </li>
27 <li> The indent size is 4 spaces.
28 <h4 class="right">Right:</h4>
29 <pre class="code">
30 int main()
31 {
32     return 0;
33 }
34 </pre>
35
36 <h4 class="wrong">Wrong:</h4>
37 <pre class="code">
38 int main() 
39 {
40         return 0;
41 }
42 </pre>
43 </li>
44 <li>In a header, code inside a namespace should be indented.
45 <h4 class="right">Right:</h4>
46 <pre class="code">
47 // Document.h
48 namespace WebCore {
49
50     class Document {
51         Document();
52         ...
53     };
54
55 } // namespace WebCore
56 </pre>
57
58 <h4 class="wrong">Wrong:</h4>
59 <pre class="code">
60 // Document.h
61 namespace WebCore {
62
63 class Document {
64     Document();
65     ...
66 };
67
68 } // namespace WebCore
69 </pre>
70 </li>
71
72 <li>In an implementation file, code inside a namespace should <em>not</em> be indented.
73 <h4 class="right">Right:</h4>
74 <pre class="code">
75 // Document.cpp
76 namespace WebCore {
77
78 Document::Document()
79 {
80     ...
81 }
82
83 } // namespace WebCore
84 </pre>
85
86 <h4 class="wrong">Wrong:</h4>
87 <pre class="code">
88 // Document.cpp
89 namespace WebCore {
90
91     Document::Document()
92     {
93         ...
94     }
95
96 } // namespace WebCore
97 </pre>
98 </li>
99 <li>A case label should line up with its switch statement.  The case statement is indented.
100 <h4 class="right">Right:</h4>
101 <pre class="code">
102 switch (condition) {
103 case fooCondition:
104 case barCondition:
105     i++;
106     break;
107 default:
108     i--;
109 }
110 </pre>
111
112 <h4 class="wrong">Wrong:</h4>
113 <pre class="code">
114 switch (condition) {
115     case fooCondition:
116     case barCondition:
117         i++;
118         break;
119     default:
120         i--;
121 }
122 </pre>
123 </li>
124 </ol>
125
126 <h3>Spacing</h3>
127 <ol>
128 <li>Do not place spaces around unary operators.
129 <h4 class="right">Right:</h4>
130 <pre class="code">
131 i++;
132 </pre>
133
134 <h4 class="wrong">Wrong:</h4>
135 <pre class="code">
136 i ++;
137 </pre>
138 </li>
139
140 <li><em>Do</em> place spaces around binary and ternary operators.
141 <h4 class="right">Right:</h4>
142 <pre class="code">
143 y = m * x + b;
144 f(a, b);
145 c = a | b;
146 return condition ? 1 : 0;
147 </pre>
148
149 <h4 class="wrong">Wrong:</h4>
150 <pre class="code">
151 y=m*x+b;
152 f(a,b);
153 c = a|b;
154 return condition ? 1:0;
155 </pre>
156 </li>
157
158 <li>Place spaces between control statements and their parentheses.
159 <h4 class="right">Right:</h4>
160 <pre class="code">
161 if (condition)
162     doIt();
163 </pre>
164
165 <h4 class="wrong">Wrong:</h4>
166 <pre class="code">
167 if(condition)
168     doIt();
169 </pre>
170 </li>
171
172 <li>Do not place spaces between a function and its parentheses, or between a parenthesis and its content.
173 <h4 class="right">Right:</h4>
174 <pre class="code">
175 f(a, b);
176 </pre>
177
178 <h4 class="wrong">Wrong:</h4>
179 <pre class="code">
180 f (a, b);
181 f( a, b );
182 </pre>
183 </li>
184 </ol>
185
186 <h3>Line breaking</h3>
187 <ol>
188 <li>Each statement should get its own line.
189 <h4 class="right">Right:</h4>
190 <pre class="code">
191 x++;
192 y++;
193 if (condition)
194     doIt();
195 </pre>
196
197 <h4 class="wrong">Wrong:</h4>
198 <pre class="code">
199 x++; y++;
200 if (condition) doIt();
201 </pre>
202 </li>
203
204 <li>An else statement should go on the same line as a preceding close brace.
205 <h4 class="right">Right:</h4>
206 <pre class="code">
207 if (condition) {
208     ...
209 } else {
210     ...
211 }
212 </pre>
213
214 <h4 class="wrong">Wrong:</h4>
215 <pre class="code">
216 if (condition) {
217     ...
218 }
219 else {
220     ...
221 }
222 </pre>
223 </li>
224 </ol>
225
226 <h3>Braces</h3>
227 <ol>
228 <li> Function definitions: place each brace on its own line.
229
230 <h4 class="right">Right:</h4>
231 <pre class="code">
232 int main()
233 {
234     ...
235 }
236 </pre>
237
238 <h4 class="wrong">Wrong:</h4>
239 <pre class="code">
240 int main() {
241     ...
242 }
243 </pre>
244 </li>
245 <li> Other braces: place the open brace on the line preceding the code block; place the close brace on its own line.
246
247 <h4 class="right">Right:</h4>
248 <pre class="code">
249 class MyClass {
250     ...
251 };
252
253 namespace WebCore {
254     ...
255 }
256
257 for (int i = 0; i &lt; 10; i++) {
258     ...
259 }
260 </pre>
261
262 <h4 class="wrong">Wrong:</h4>
263 <pre class="code">
264 class MyClass 
265 {
266     ...
267 };
268 </pre>
269 <li>One-line control clauses should not use braces
270 <h4 class="right">Right:</h4>
271 <pre class="code">
272 if (condition)
273     doIt();
274 </pre>
275
276 <h4 class="wrong">Wrong:</h4>
277 <pre class="code">
278 if (condition) {
279     doIt();
280 }
281 </pre>
282 </li>
283
284 <li>Control clauses without a body should use empty braces:
285 <h4 class="right">Right:</h4>
286 <pre class="code">
287 for ( ; current; current = current->next) { }
288 </pre>
289
290 <h4 class="wrong">Wrong:</h4>
291 <pre class="code">
292 for ( ; current; current = current->next);
293 </pre>
294 </li>
295 </ol>
296
297 <h3>Null, false and 0</h3>
298 <ol>
299 <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 and Objective-C++, follow the guideline for C or C++, respectively, but use <code>nil</code> to represent a null Objective-C object.</li>
300 <li>C++ and C <code>bool</code> values should be written as <code>true</code> and <code>false</code>. Objective-C <code>BOOL</code> values should be written as <code>YES</code> and <code>NO</code>.</li>
301 <li>Tests for true/false, null/non-null, and zero/non-zero should all be done without equality comparisons.<br>
302
303 <h4 class="right">Right:</h4>
304 <pre class="code">
305 if (condition)
306     doIt();
307     
308 if (!ptr)
309     return;
310
311 if (!count)
312     return;
313 </pre>
314
315 <h4 class="wrong">Wrong:</h4>
316 <pre class="code">
317 if (condition == true)
318     doIt();
319     
320 if (ptr == NULL)
321     return;
322     
323 if (count == 0)
324     return;
325 </pre>
326 </li>
327 </ol>
328
329 <h3>Names</h3>
330 <ol>
331 <li>Use CamelCase. Capitalize the first letter of a class, struct, protocol, or namespace name. Lower-case the first letter of a variable or function name. Fully capitalize acronyms.
332 <h4 class="right">Right:</h4>
333 <pre class="code">
334 struct Data;
335 size_t bufferSize;
336 class HTMLDocument;
337 </pre>
338
339 <h4 class="wrong">Wrong:</h4>
340 <pre class="code">
341 struct data;
342 size_t buffer_size;
343 class HtmlDocument;
344 </pre>
345 </li>
346
347 <li>Use full words, except in the rare case where an abbreviation would be more canonical and easier to understand.
348 <h4 class="right">Right:</h4>
349 <pre class="code">
350 size_t characterSize;
351 size_t length;
352 short tabIndex; // more canonical
353 </pre>
354
355 <h4 class="wrong">Wrong:</h4>
356 <pre class="code">
357 size_t charSize;
358 size_t len;
359 short tabulationIndex; // bizarre
360 </pre>
361 </li>
362
363 <li>Prefix C++ data members with "m_".
364 <h4 class="right">Right:</h4>
365 <pre class="code">
366 class String {
367     ...
368     short m_length;
369 };
370 </pre>
371
372 <h4 class="wrong">Wrong:</h4>
373 <pre class="code">
374 class String {
375     ...
376     short length;
377 };
378 </pre>
379 </li>
380
381 <li>Prefix Objective-C instance variables with "_".
382 <h4 class="right">Right:</h4>
383 <pre class="code">
384 @class String
385     ...
386     short _length;
387 @end
388 </pre>
389
390 <h4 class="wrong">Wrong:</h4>
391 <pre class="code">
392 @class String
393     ...
394     short length;
395 @end
396 </pre>
397 </li>
398
399 <li>Precede boolean values with words like "is" and "did".
400 <h4 class="right">Right:</h4>
401 <pre class="code">
402 bool isValid;
403 bool didSendData;
404 </pre>
405
406 <h4 class="wrong">Wrong:</h4>
407 <pre class="code">
408 bool valid;
409 bool sentData;
410 </pre>
411 </li>
412
413 <li>Precede setters with the word "set". Use bare words for getters. Setter and getter names should match the names of the variables being set/gotten.
414 <h4 class="right">Right:</h4>
415 <pre class="code">
416 void setCount(size_t); // sets m_count
417 size_t count(); // returns m_count
418 </pre>
419
420 <h4 class="wrong">Wrong:</h4>
421 <pre class="code">
422 void setCount(size_t); // sets m_theCount
423 size_t getCount();
424 </pre>
425 </li>
426
427 <li>Use descriptive verbs in function names.
428 <h4 class="right">Right:</h4>
429 <pre class="code">
430 bool convertToASCII(short*, size_t);
431 </pre>
432
433 <h4 class="wrong">Wrong:</h4>
434 <pre class="code">
435 bool toASCII(short*, size_t);
436 </pre>
437 </li>
438
439 <li>Leave meaningless variable names out of function declarations.
440 <h4 class="right">Right:</h4>
441 <pre class="code">
442 void setCount(size_t);
443 </pre>
444
445 <h4 class="wrong">Wrong:</h4>
446 <pre class="code">
447 void setCount(size_t count);
448 </pre>
449 </li>
450
451 <li>Objective-C method names should follow the Cocoa naming guidelines &mdash;
452 they should read like a phrase and each piece of the selector should 
453 start with a lowercase letter and use intercaps.</li>
454 <li>Enum members should user InterCaps with an initial capital letter.</li>
455 <li>Prefer const to #define. Prefer inline functions to macros.</li>
456 <li>#defined constants should use all uppercase names with words separated by underscores.</li>
457 <li> Macros that expand to function calls or other non-constant computation: these 
458 should be named like functions, and should have parentheses at the end, even if 
459 they take no arguments (with the exception of some special macros like ASSERT). 
460 Note that usually it is preferable to use an inline function in such cases instead of a macro.<br>
461
462 <h4 class="right">Right:</h4>
463 <pre class="code">
464 #define WBStopButtonTitle() \
465         NSLocalizedString(@"Stop", @"Stop button title")
466 </pre>
467
468 <h4 class="wrong">Wrong:</h4>
469 <pre class="code">
470 #define WB_STOP_BUTTON_TITLE \
471         NSLocalizedString(@"Stop", @"Stop button title")
472
473 #define WBStopButtontitle \
474         NSLocalizedString(@"Stop", @"Stop button title")
475 </pre>
476 </li>
477 <li>#define, #ifdef "header guards" should be named exactly the same as the file (including case), replacing the '.' with a '_'.
478 <h4 class="right">Right:</h4>
479 <pre class="code">
480 // HTMLDocument.h
481 #ifndef HTMLDocument_h
482 #define HTMLDocument_h
483 </pre>
484
485 <h4 class="wrong">Wrong:</h4>
486 <pre class="code">
487 // HTMLDocument.h
488 #ifndef _HTML_DOCUMENT_H_
489 #define _HTML_DOCUMENT_H_
490 </pre>
491 </li>
492 </ol>
493
494 <h3>Other Punctuation</h3>
495
496 <ol>
497
498 <li>Constructors for C++ classes should initialize all of their members using C++ 
499 initializer syntax.  Each member (and superclass) should be indented on a separate 
500 line, with the colon or comma preceding the member on that line.
501
502 <h4 class="right">Right:</h4>
503 <pre class="code">
504 MyClass::MyClass(Document* doc)
505     : MySuperClass()
506     , m_myMember(0)
507     , m_doc(doc)
508 {
509 }
510
511 MyOtherClass::MyOtherClass()
512     : MySuperClass()
513 {
514 }
515 </pre>
516
517 <h4 class="wrong">Wrong:</h4>
518 <pre class="code">
519 MyClass::MyClass(Document* doc) : MySuperClass()
520 {
521     m_myMember = 0;
522     m_doc = doc;
523 }
524
525 MyOtherClass::MyOtherClass() : MySuperClass() {}
526 </pre>
527
528 <li>Pointer types in non-C++ code &mdash; Pointer types should be written with a space between the
529 type and the * (so the * is adjacent to the following identifier if any).
530
531 <li>Pointer and reference types in C++ code &mdash; Both pointer types and reference types
532 should be written with no space between the type name and the * or &amp;.
533
534 <h4 class="right">Right:</h4>
535 <pre class="code">
536 Image* SVGStyledElement::doSomething(PaintInfo&amp; paintInfo)
537 {
538   SVGStyledElement* element = static_cast&lt;SVGStyledElement*>(node());
539   const KCDashArray&amp; dashes = dashArray();
540 </pre>
541
542 <h4 class="wrong">Wrong:</h4>
543 <pre class="code">
544 Image *SVGStyledElement::doSomething(PaintInfo &amp;paintInfo)
545 {
546     SVGStyledElement *element = static_cast&lt;SVGStyledElement *>(node());
547     const KCDashArray &amp;dashes = dashArray();
548 </pre>
549
550 </ol>
551
552 <h3>#include Statements</h3>
553
554 <ol>
555
556 <li>All files must #include "config.h" first.
557
558 <li>All files must #include the primary header second, just after "config.h".
559 So for example, Node.cpp should include Node.h first, before other files.
560 This guarantees that each header's completeness is tested, to make sure it
561 can be compiled without requiring any other header files be included first.
562
563 <li>Other #include statements should be in sorted order (case sensitive, as
564 done by the command-line sort tool or the Xcode sort selection command).
565 Don't bother to organize them in a logical order.
566
567 </ol>
568
569 <?php
570     include("../footer.inc");
571 ?>