2008-03-21 Cameron Zwarich <cwzwarich@uwaterloo.ca>
[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 <code>else</code> 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
225 <li>An <code>else if</code> statement should be written as an <code>if</code> statement when the prior <code>if</code> concludes with a <code>return</code> statement.
226 <h4 class="right">Right:</h4>
227 <pre class="code">
228 if (condition) {
229     ...
230     return someValue;
231 }
232 if (condition) {
233     ...
234 }
235 </pre>
236
237 <h4 class="wrong">Wrong:</h4>
238 <pre class="code">
239 if (condition) {
240     ...
241     return someValue;
242 } else if (condition) {
243     ...
244 }
245 </pre>
246 </li>
247 </ol>
248
249 <h3>Braces</h3>
250 <ol>
251 <li> Function definitions: place each brace on its own line.
252
253 <h4 class="right">Right:</h4>
254 <pre class="code">
255 int main()
256 {
257     ...
258 }
259 </pre>
260
261 <h4 class="wrong">Wrong:</h4>
262 <pre class="code">
263 int main() {
264     ...
265 }
266 </pre>
267 </li>
268 <li> Other braces: place the open brace on the line preceding the code block; place the close brace on its own line.
269
270 <h4 class="right">Right:</h4>
271 <pre class="code">
272 class MyClass {
273     ...
274 };
275
276 namespace WebCore {
277     ...
278 }
279
280 for (int i = 0; i &lt; 10; i++) {
281     ...
282 }
283 </pre>
284
285 <h4 class="wrong">Wrong:</h4>
286 <pre class="code">
287 class MyClass 
288 {
289     ...
290 };
291 </pre>
292 <li>One-line control clauses should not use braces
293 <h4 class="right">Right:</h4>
294 <pre class="code">
295 if (condition)
296     doIt();
297 </pre>
298
299 <h4 class="wrong">Wrong:</h4>
300 <pre class="code">
301 if (condition) {
302     doIt();
303 }
304 </pre>
305 </li>
306
307 <li>Control clauses without a body should use empty braces:
308 <h4 class="right">Right:</h4>
309 <pre class="code">
310 for ( ; current; current = current->next) { }
311 </pre>
312
313 <h4 class="wrong">Wrong:</h4>
314 <pre class="code">
315 for ( ; current; current = current->next);
316 </pre>
317 </li>
318 </ol>
319
320 <h3>Null, false and 0</h3>
321 <ol>
322 <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>
323 <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>
324 <li>Tests for true/false, null/non-null, and zero/non-zero should all be done without equality comparisons.<br>
325
326 <h4 class="right">Right:</h4>
327 <pre class="code">
328 if (condition)
329     doIt();
330     
331 if (!ptr)
332     return;
333
334 if (!count)
335     return;
336 </pre>
337
338 <h4 class="wrong">Wrong:</h4>
339 <pre class="code">
340 if (condition == true)
341     doIt();
342     
343 if (ptr == NULL)
344     return;
345     
346 if (count == 0)
347     return;
348 </pre>
349 </li>
350 <li>In Objective-C, instance variables are initialized to zero automatically. Don't add explicit initializations to nil or NO in an init method.</li>
351 </ol>
352
353 <h3>Names</h3>
354 <ol>
355 <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.
356 <h4 class="right">Right:</h4>
357 <pre class="code">
358 struct Data;
359 size_t bufferSize;
360 class HTMLDocument;
361 </pre>
362
363 <h4 class="wrong">Wrong:</h4>
364 <pre class="code">
365 struct data;
366 size_t buffer_size;
367 class HtmlDocument;
368 </pre>
369 </li>
370
371 <li>Use full words, except in the rare case where an abbreviation would be more canonical and easier to understand.
372 <h4 class="right">Right:</h4>
373 <pre class="code">
374 size_t characterSize;
375 size_t length;
376 short tabIndex; // more canonical
377 </pre>
378
379 <h4 class="wrong">Wrong:</h4>
380 <pre class="code">
381 size_t charSize;
382 size_t len;
383 short tabulationIndex; // bizarre
384 </pre>
385 </li>
386
387 <li>Prefix C++ data members with "m_".
388 <h4 class="right">Right:</h4>
389 <pre class="code">
390 class String {
391     ...
392     short m_length;
393 };
394 </pre>
395
396 <h4 class="wrong">Wrong:</h4>
397 <pre class="code">
398 class String {
399     ...
400     short length;
401 };
402 </pre>
403 </li>
404
405 <li>Prefix Objective-C instance variables with "_".
406 <h4 class="right">Right:</h4>
407 <pre class="code">
408 @class String
409     ...
410     short _length;
411 @end
412 </pre>
413
414 <h4 class="wrong">Wrong:</h4>
415 <pre class="code">
416 @class String
417     ...
418     short length;
419 @end
420 </pre>
421 </li>
422
423 <li>Precede boolean values with words like "is" and "did".
424 <h4 class="right">Right:</h4>
425 <pre class="code">
426 bool isValid;
427 bool didSendData;
428 </pre>
429
430 <h4 class="wrong">Wrong:</h4>
431 <pre class="code">
432 bool valid;
433 bool sentData;
434 </pre>
435 </li>
436
437 <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.
438 <h4 class="right">Right:</h4>
439 <pre class="code">
440 void setCount(size_t); // sets m_count
441 size_t count(); // returns m_count
442 </pre>
443
444 <h4 class="wrong">Wrong:</h4>
445 <pre class="code">
446 void setCount(size_t); // sets m_theCount
447 size_t getCount();
448 </pre>
449 </li>
450
451 <li>Use descriptive verbs in function names.
452 <h4 class="right">Right:</h4>
453 <pre class="code">
454 bool convertToASCII(short*, size_t);
455 </pre>
456
457 <h4 class="wrong">Wrong:</h4>
458 <pre class="code">
459 bool toASCII(short*, size_t);
460 </pre>
461 </li>
462
463 <li>Leave meaningless variable names out of function declarations.
464 <h4 class="right">Right:</h4>
465 <pre class="code">
466 void setCount(size_t);
467 </pre>
468
469 <h4 class="wrong">Wrong:</h4>
470 <pre class="code">
471 void setCount(size_t count);
472 </pre>
473 </li>
474
475 <li>Objective-C method names should follow the Cocoa naming guidelines &mdash;
476 they should read like a phrase and each piece of the selector should 
477 start with a lowercase letter and use intercaps.</li>
478 <li>Enum members should user InterCaps with an initial capital letter.</li>
479 <li>Prefer const to #define. Prefer inline functions to macros.</li>
480 <li>#defined constants should use all uppercase names with words separated by underscores.</li>
481 <li> Macros that expand to function calls or other non-constant computation: these 
482 should be named like functions, and should have parentheses at the end, even if 
483 they take no arguments (with the exception of some special macros like ASSERT). 
484 Note that usually it is preferable to use an inline function in such cases instead of a macro.<br>
485
486 <h4 class="right">Right:</h4>
487 <pre class="code">
488 #define WBStopButtonTitle() \
489         NSLocalizedString(@"Stop", @"Stop button title")
490 </pre>
491
492 <h4 class="wrong">Wrong:</h4>
493 <pre class="code">
494 #define WB_STOP_BUTTON_TITLE \
495         NSLocalizedString(@"Stop", @"Stop button title")
496
497 #define WBStopButtontitle \
498         NSLocalizedString(@"Stop", @"Stop button title")
499 </pre>
500 </li>
501 <li>#define, #ifdef "header guards" should be named exactly the same as the file (including case), replacing the '.' with a '_'.
502 <h4 class="right">Right:</h4>
503 <pre class="code">
504 // HTMLDocument.h
505 #ifndef HTMLDocument_h
506 #define HTMLDocument_h
507 </pre>
508
509 <h4 class="wrong">Wrong:</h4>
510 <pre class="code">
511 // HTMLDocument.h
512 #ifndef _HTML_DOCUMENT_H_
513 #define _HTML_DOCUMENT_H_
514 </pre>
515 </li>
516 </ol>
517
518 <h3>Other Punctuation</h3>
519
520 <ol>
521
522 <li>Constructors for C++ classes should initialize all of their members using C++ 
523 initializer syntax.  Each member (and superclass) should be indented on a separate 
524 line, with the colon or comma preceding the member on that line.
525
526 <h4 class="right">Right:</h4>
527 <pre class="code">
528 MyClass::MyClass(Document* doc)
529     : MySuperClass()
530     , m_myMember(0)
531     , m_doc(doc)
532 {
533 }
534
535 MyOtherClass::MyOtherClass()
536     : MySuperClass()
537 {
538 }
539 </pre>
540
541 <h4 class="wrong">Wrong:</h4>
542 <pre class="code">
543 MyClass::MyClass(Document* doc) : MySuperClass()
544 {
545     m_myMember = 0;
546     m_doc = doc;
547 }
548
549 MyOtherClass::MyOtherClass() : MySuperClass() {}
550 </pre>
551
552 <li>Pointer types in non-C++ code &mdash; Pointer types should be written with a space between the
553 type and the * (so the * is adjacent to the following identifier if any).
554
555 <li>Pointer and reference types in C++ code &mdash; Both pointer types and reference types
556 should be written with no space between the type name and the * or &amp;.
557
558 <h4 class="right">Right:</h4>
559 <pre class="code">
560 Image* SVGStyledElement::doSomething(PaintInfo&amp; paintInfo)
561 {
562   SVGStyledElement* element = static_cast&lt;SVGStyledElement*>(node());
563   const KCDashArray&amp; dashes = dashArray();
564 </pre>
565
566 <h4 class="wrong">Wrong:</h4>
567 <pre class="code">
568 Image *SVGStyledElement::doSomething(PaintInfo &amp;paintInfo)
569 {
570     SVGStyledElement *element = static_cast&lt;SVGStyledElement *>(node());
571     const KCDashArray &amp;dashes = dashArray();
572 </pre>
573
574 </ol>
575
576 <h3>#include Statements</h3>
577
578 <ol>
579
580 <li>All files must #include "config.h" first.
581
582 <li>All files must #include the primary header second, just after "config.h".
583 So for example, Node.cpp should include Node.h first, before other files.
584 This guarantees that each header's completeness is tested, to make sure it
585 can be compiled without requiring any other header files be included first.
586
587 <li>Other #include statements should be in sorted order (case sensitive, as
588 done by the command-line sort tool or the Xcode sort selection command).
589 Don't bother to organize them in a logical order.
590
591 </ol>
592
593 <?php
594     include("../footer.inc");
595 ?>