Fix for https://bugs.webkit.org/show_bug.cgi?id=30196
[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>Code inside a namespace should not 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
57 // Document.cpp
58 namespace WebCore {
59
60 Document::Document()
61 {
62     ...
63 }
64
65 } // namespace WebCore
66 </pre>
67
68 <h4 class="wrong">Wrong:</h4>
69 <pre class="code">
70 // Document.h
71 namespace WebCore {
72
73     class Document {
74         Document();
75         ...
76     };
77
78 } // namespace WebCore
79
80 // Document.cpp
81 namespace WebCore {
82
83     Document::Document()
84     {
85         ...
86     }
87
88 } // namespace WebCore
89 </pre>
90 </li>
91
92 <li>A case label should line up with its switch statement.  The case statement is indented.
93 <h4 class="right">Right:</h4>
94 <pre class="code">
95 switch (condition) {
96 case fooCondition:
97 case barCondition:
98     i++;
99     break;
100 default:
101     i--;
102 }
103 </pre>
104
105 <h4 class="wrong">Wrong:</h4>
106 <pre class="code">
107 switch (condition) {
108     case fooCondition:
109     case barCondition:
110         i++;
111         break;
112     default:
113         i--;
114 }
115 </pre>
116 </li>
117
118 <li>Boolean expressions at the same nesting level that span multiple lines should
119 have their operators on the left side of the line instead of the right side.
120
121 <h4 class="right">Right:</h4>
122 <pre class="code">
123 return attr->name() == srcAttr
124     || attr->name() == lowsrcAttr
125     || (attr->name() == usemapAttr && attr->value().domString()[0] != '#');
126 </pre>
127
128 <h4 class="wrong">Wrong:</h4>
129 <pre class="code">
130 return attr->name() == srcAttr ||
131     attr->name() == lowsrcAttr ||
132     (attr->name() == usemapAttr && attr->value().domString()[0] != '#');
133 </pre>
134 </li>
135
136 </ol>
137
138 <h3>Spacing</h3>
139 <ol>
140 <li>Do not place spaces around unary operators.
141 <h4 class="right">Right:</h4>
142 <pre class="code">
143 i++;
144 </pre>
145
146 <h4 class="wrong">Wrong:</h4>
147 <pre class="code">
148 i ++;
149 </pre>
150 </li>
151
152 <li><em>Do</em> place spaces around binary and ternary operators.
153 <h4 class="right">Right:</h4>
154 <pre class="code">
155 y = m * x + b;
156 f(a, b);
157 c = a | b;
158 return condition ? 1 : 0;
159 </pre>
160
161 <h4 class="wrong">Wrong:</h4>
162 <pre class="code">
163 y=m*x+b;
164 f(a,b);
165 c = a|b;
166 return condition ? 1:0;
167 </pre>
168 </li>
169
170 <li>Do not place spaces before comma and semicolon.
171 <h4 class="right">Right:</h4>
172 <pre class="code">
173 for (int i = 0; i < 10; i++)
174     doSomething();
175
176 f(a, b);
177 </pre>
178
179 <h4 class="wrong">Wrong:</h4>
180 <pre class="code">
181 for (int i = 0 ; i < 10 ; i++)
182     doSomething();
183
184 f(a , b) ;
185 </pre>
186 </li>
187
188 <li>Place spaces between control statements and their parentheses.
189 <h4 class="right">Right:</h4>
190 <pre class="code">
191 if (condition)
192     doIt();
193 </pre>
194
195 <h4 class="wrong">Wrong:</h4>
196 <pre class="code">
197 if(condition)
198     doIt();
199 </pre>
200 </li>
201
202 <li>Do not place spaces between a function and its parentheses, or between a parenthesis and its content.
203 <h4 class="right">Right:</h4>
204 <pre class="code">
205 f(a, b);
206 </pre>
207
208 <h4 class="wrong">Wrong:</h4>
209 <pre class="code">
210 f (a, b);
211 f( a, b );
212 </pre>
213 </li>
214 </ol>
215
216 <h3>Line breaking</h3>
217 <ol>
218 <li>Each statement should get its own line.
219 <h4 class="right">Right:</h4>
220 <pre class="code">
221 x++;
222 y++;
223 if (condition)
224     doIt();
225 </pre>
226
227 <h4 class="wrong">Wrong:</h4>
228 <pre class="code">
229 x++; y++;
230 if (condition) doIt();
231 </pre>
232 </li>
233
234 <li>An <code>else</code> statement should go on the same line as a preceding close brace if one is present,
235 else it should line up with the <code>if</code> statement.
236 <h4 class="right">Right:</h4>
237 <pre class="code">
238 if (condition) {
239     ...
240 } else {
241     ...
242 }
243
244 if (condition)
245     doSomething();
246 else
247     doSomethingElse();
248
249 if (condition)
250     doSomething();
251 else {
252     ...
253 }
254 </pre>
255
256 <h4 class="wrong">Wrong:</h4>
257 <pre class="code">
258 if (condition) {
259     ...
260 }
261 else {
262     ...
263 }
264
265 if (condition) doSomething(); else doSomethingElse();
266
267 if (condition) doSomething(); else {
268     ...
269 }
270 </pre>
271 </li>
272
273 <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.
274 <h4 class="right">Right:</h4>
275 <pre class="code">
276 if (condition) {
277     ...
278     return someValue;
279 }
280 if (condition) {
281     ...
282 }
283 </pre>
284
285 <h4 class="wrong">Wrong:</h4>
286 <pre class="code">
287 if (condition) {
288     ...
289     return someValue;
290 } else if (condition) {
291     ...
292 }
293 </pre>
294 </li>
295 </ol>
296
297 <h3>Braces</h3>
298 <ol>
299 <li> Function definitions: place each brace on its own line.
300
301 <h4 class="right">Right:</h4>
302 <pre class="code">
303 int main()
304 {
305     ...
306 }
307 </pre>
308
309 <h4 class="wrong">Wrong:</h4>
310 <pre class="code">
311 int main() {
312     ...
313 }
314 </pre>
315 </li>
316 <li> Other braces: place the open brace on the line preceding the code block; place the close brace on its own line.
317
318 <h4 class="right">Right:</h4>
319 <pre class="code">
320 class MyClass {
321     ...
322 };
323
324 namespace WebCore {
325     ...
326 }
327
328 for (int i = 0; i &lt; 10; i++) {
329     ...
330 }
331 </pre>
332
333 <h4 class="wrong">Wrong:</h4>
334 <pre class="code">
335 class MyClass 
336 {
337     ...
338 };
339 </pre>
340 <li>One-line control clauses should not use braces unless comments are included
341 or a single statement spans multiple lines.
342 <h4 class="right">Right:</h4>
343 <pre class="code">
344 if (condition)
345     doIt();
346
347 if (condition) {
348     // Some comment
349     doIt();
350 }
351
352 if (condition) {
353     myFunction(reallyLongParam1, reallyLongParam2, ...
354         reallyLongParam5);
355 }
356 </pre>
357
358 <h4 class="wrong">Wrong:</h4>
359 <pre class="code">
360 if (condition) {
361     doIt();
362 }
363
364 if (condition)
365     // Some comment
366     doIt();
367
368 if (condition)
369     myFunction(reallyLongParam1, reallyLongParam2, ...
370         reallyLongParam5);
371 </pre>
372 </li>
373
374 <li>Control clauses without a body should use empty braces:
375 <h4 class="right">Right:</h4>
376 <pre class="code">
377 for ( ; current; current = current->next) { }
378 </pre>
379
380 <h4 class="wrong">Wrong:</h4>
381 <pre class="code">
382 for ( ; current; current = current->next);
383 </pre>
384 </li>
385 </ol>
386
387 <h3>Null, false and 0</h3>
388 <ol>
389 <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>
390 <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>
391 <li>Tests for true/false, null/non-null, and zero/non-zero should all be done without equality comparisons.<br>
392
393 <h4 class="right">Right:</h4>
394 <pre class="code">
395 if (condition)
396     doIt();
397     
398 if (!ptr)
399     return;
400
401 if (!count)
402     return;
403 </pre>
404
405 <h4 class="wrong">Wrong:</h4>
406 <pre class="code">
407 if (condition == true)
408     doIt();
409     
410 if (ptr == NULL)
411     return;
412     
413 if (count == 0)
414     return;
415 </pre>
416 </li>
417 <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>
418 </ol>
419
420 <h3>Names</h3>
421 <ol>
422 <li>Use CamelCase. Capitalize the first letter, including all letters in an acronym, in a class, struct, protocol, or namespace name. Lower-case the first letter, including all letters in an acronym, in a variable or function name.
423 <h4 class="right">Right:</h4>
424 <pre class="code">
425 struct Data;
426 size_t bufferSize;
427 class HTMLDocument;
428 String mimeType();
429 </pre>
430
431 <h4 class="wrong">Wrong:</h4>
432 <pre class="code">
433 struct data;
434 size_t buffer_size;
435 class HtmlDocument;
436 String MIMEType();
437 </pre>
438 </li>
439
440 <li>Use full words, except in the rare case where an abbreviation would be more canonical and easier to understand.
441 <h4 class="right">Right:</h4>
442 <pre class="code">
443 size_t characterSize;
444 size_t length;
445 short tabIndex; // more canonical
446 </pre>
447
448 <h4 class="wrong">Wrong:</h4>
449 <pre class="code">
450 size_t charSize;
451 size_t len;
452 short tabulationIndex; // bizarre
453 </pre>
454 </li>
455
456 <li>Prefix C++ data members with "m_".
457 <h4 class="right">Right:</h4>
458 <pre class="code">
459 class String {
460     ...
461     short m_length;
462 };
463 </pre>
464
465 <h4 class="wrong">Wrong:</h4>
466 <pre class="code">
467 class String {
468     ...
469     short length;
470 };
471 </pre>
472 </li>
473
474 <li>Prefix Objective-C instance variables with "_".
475 <h4 class="right">Right:</h4>
476 <pre class="code">
477 @class String
478     ...
479     short _length;
480 @end
481 </pre>
482
483 <h4 class="wrong">Wrong:</h4>
484 <pre class="code">
485 @class String
486     ...
487     short length;
488 @end
489 </pre>
490 </li>
491
492 <li>Precede boolean values with words like "is" and "did".
493 <h4 class="right">Right:</h4>
494 <pre class="code">
495 bool isValid;
496 bool didSendData;
497 </pre>
498
499 <h4 class="wrong">Wrong:</h4>
500 <pre class="code">
501 bool valid;
502 bool sentData;
503 </pre>
504 </li>
505
506 <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.
507 <h4 class="right">Right:</h4>
508 <pre class="code">
509 void setCount(size_t); // sets m_count
510 size_t count(); // returns m_count
511 </pre>
512
513 <h4 class="wrong">Wrong:</h4>
514 <pre class="code">
515 void setCount(size_t); // sets m_theCount
516 size_t getCount();
517 </pre>
518 </li>
519
520 <li>Use descriptive verbs in function names.
521 <h4 class="right">Right:</h4>
522 <pre class="code">
523 bool convertToASCII(short*, size_t);
524 </pre>
525
526 <h4 class="wrong">Wrong:</h4>
527 <pre class="code">
528 bool toASCII(short*, size_t);
529 </pre>
530 </li>
531
532 <li>Leave meaningless variable names out of function declarations.
533 <h4 class="right">Right:</h4>
534 <pre class="code">
535 void setCount(size_t);
536 </pre>
537
538 <h4 class="wrong">Wrong:</h4>
539 <pre class="code">
540 void setCount(size_t count);
541 </pre>
542 </li>
543
544 <li>Objective-C method names should follow the Cocoa naming guidelines &mdash;
545 they should read like a phrase and each piece of the selector should 
546 start with a lowercase letter and use intercaps.</li>
547 <li>Enum members should user InterCaps with an initial capital letter.</li>
548 <li>Prefer const to #define. Prefer inline functions to macros.</li>
549 <li>#defined constants should use all uppercase names with words separated by underscores.</li>
550 <li> Macros that expand to function calls or other non-constant computation: these 
551 should be named like functions, and should have parentheses at the end, even if 
552 they take no arguments (with the exception of some special macros like ASSERT). 
553 Note that usually it is preferable to use an inline function in such cases instead of a macro.<br>
554
555 <h4 class="right">Right:</h4>
556 <pre class="code">
557 #define WBStopButtonTitle() \
558         NSLocalizedString(@"Stop", @"Stop button title")
559 </pre>
560
561 <h4 class="wrong">Wrong:</h4>
562 <pre class="code">
563 #define WB_STOP_BUTTON_TITLE \
564         NSLocalizedString(@"Stop", @"Stop button title")
565
566 #define WBStopButtontitle \
567         NSLocalizedString(@"Stop", @"Stop button title")
568 </pre>
569 </li>
570 <li>#define, #ifdef "header guards" should be named exactly the same as the file (including case), replacing the '.' with a '_'.
571 <h4 class="right">Right:</h4>
572 <pre class="code">
573 // HTMLDocument.h
574 #ifndef HTMLDocument_h
575 #define HTMLDocument_h
576 </pre>
577
578 <h4 class="wrong">Wrong:</h4>
579 <pre class="code">
580 // HTMLDocument.h
581 #ifndef _HTML_DOCUMENT_H_
582 #define _HTML_DOCUMENT_H_
583 </pre>
584 </li>
585 </ol>
586
587 <h3>Other Punctuation</h3>
588
589 <ol>
590
591 <li>Constructors for C++ classes should initialize all of their members using C++ 
592 initializer syntax.  Each member (and superclass) should be indented on a separate 
593 line, with the colon or comma preceding the member on that line.
594
595 <h4 class="right">Right:</h4>
596 <pre class="code">
597 MyClass::MyClass(Document* doc)
598     : MySuperClass()
599     , m_myMember(0)
600     , m_doc(doc)
601 {
602 }
603
604 MyOtherClass::MyOtherClass()
605     : MySuperClass()
606 {
607 }
608 </pre>
609
610 <h4 class="wrong">Wrong:</h4>
611 <pre class="code">
612 MyClass::MyClass(Document* doc) : MySuperClass()
613 {
614     m_myMember = 0;
615     m_doc = doc;
616 }
617
618 MyOtherClass::MyOtherClass() : MySuperClass() {}
619 </pre>
620
621 <li>Pointer types in non-C++ code &mdash; Pointer types should be written with a space between the
622 type and the * (so the * is adjacent to the following identifier if any).
623
624 <li>Pointer and reference types in C++ code &mdash; Both pointer types and reference types
625 should be written with no space between the type name and the * or &amp;.
626
627 <h4 class="right">Right:</h4>
628 <pre class="code">
629 Image* SVGStyledElement::doSomething(PaintInfo&amp; paintInfo)
630 {
631     SVGStyledElement* element = static_cast&lt;SVGStyledElement*>(node());
632     const KCDashArray&amp; dashes = dashArray();
633 </pre>
634
635 <h4 class="wrong">Wrong:</h4>
636 <pre class="code">
637 Image *SVGStyledElement::doSomething(PaintInfo &amp;paintInfo)
638 {
639     SVGStyledElement *element = static_cast&lt;SVGStyledElement *>(node());
640     const KCDashArray &amp;dashes = dashArray();
641 </pre>
642
643 </ol>
644
645 <h3>#include Statements</h3>
646
647 <ol>
648
649 <li>All implementation files must #include "config.h" first. Header
650 files should never include "config.h".
651
652 <h4 class="right">Right:</h4>
653 <pre class="code">
654 // RenderLayer.h
655 #include "Node.h"
656 #include "RenderObject.h"
657 #include "RenderView.h"
658 </pre>
659
660 <h4 class="wrong">Wrong:</h4>
661 <pre class="code">
662 // RenderLayer.h
663 #include "config.h"
664
665 #include "RenderObject.h"
666 #include "RenderView.h"
667 #include "Node.h"
668 </pre>
669
670 <li>All implementation files must #include the primary header second,
671 just after "config.h". So for example, Node.cpp should include Node.h first,
672 before other files. This guarantees that each header's completeness is tested.
673 This also assures that each header can be compiled without requiring any other
674 header files be included first.
675
676 <li>Other #include statements should be in sorted order (case sensitive, as
677 done by the command-line sort tool or the Xcode sort selection command).
678 Don't bother to organize them in a logical order.
679
680 <h4 class="right">Right:</h4>
681 <pre class="code">
682 // HTMLDivElement.cpp
683 #include "config.h"
684 #include "HTMLDivElement.h"
685
686 #include "Attribute.h"
687 #include "HTMLElement.h"
688 #include "QualifiedName.h"
689
690 </pre>
691
692 <h4 class="wrong">Wrong:</h4>
693 <pre class="code">
694 // HTMLDivElement.cpp
695 #include "HTMLElement.h"
696 #include "HTMLDivElement.h"
697 #include "QualifiedName.h"
698 #include "Attribute.h"
699 </pre>
700 </ol>
701
702 <h3>"using namespace" Statements</h3>
703
704 <ol>
705
706 <li>Any "using namespace" statements for a nested namespace whose parent namespace 
707 is also defined in a file must be declared within that namespace definition.
708
709 <h4 class="right">Right:</h4>
710 <pre class="code">
711 // HTMLBaseElement.cpp
712
713 namespace WebCore {
714
715 using namespace HTMLNames;
716
717 } // namespace WebCore
718 </pre>
719
720 <h4 class="wrong">Wrong:</h4>
721 <pre class="code">
722 // HTMLBaseElement.cpp
723
724 using namespace WebCore::HTMLNames;
725
726 namespace WebCore {
727
728 } // namespace WebCore
729 </pre>
730
731 <li>Any other "using namespace" statements must be declared before the first namespace 
732 definition in the file.
733 <h4 class="right">Right:</h4>
734 <pre class="code">
735 // HTMLSelectElement.cpp
736
737 using namespace std;
738
739 namespace WebCore {
740
741 } // namespace WebCore
742 </pre>
743
744 <h4 class="wrong">Wrong:</h4>
745 <pre class="code">
746 // HTMLSelectElement.cpp
747
748 namespace WebCore {
749
750 using namespace std;
751
752 } // namespace WebCore
753 </pre>
754 </ol>
755
756 <?php
757     include("../footer.inc");
758 ?>