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