2010-09-22 Balazs Kelemen <kb@inf.u-szeged.hu>
[WebKit-https.git] / WebKitSite / coding / coding-style.html
1 <?php 
2     $title="WebKit Coding Style Guidelines";
3     
4     $extra_head_content = <<<END
5 <style type="text/css">
6 pre .code {
7    background-color: #F2F2F2;
8 }
9
10 .right {
11   color: #080 !important;
12 }
13
14 .wrong {
15   color: #f00 !important;
16 }
17 </style>
18
19
20 END;
21
22     include("../header.inc"); 
23 ?>
24
25 <h2>WebKit Coding Style Guidelines</h2>
26 <h3>Indentation</h3>
27
28 <ol>
29 <li> Use spaces, not tabs. Tabs should only appear in files that require them for semantic meaning, like Makefiles.
30 </li>
31 <li> The indent size is 4 spaces.
32 <h4 class="right">Right:</h4>
33 <pre class="code">
34 int main()
35 {
36     return 0;
37 }
38 </pre>
39
40 <h4 class="wrong">Wrong:</h4>
41 <pre class="code">
42 int main() 
43 {
44         return 0;
45 }
46 </pre>
47 </li>
48 <li>The contents of an outermost <code>namespace</code> block (and any nested namespaces with the same scope)
49 should not be indented. The contents of other nested namespaces should be indented.
50 <h4 class="right">Right:</h4>
51 <pre class="code">
52 // Document.h
53 namespace WebCore {
54
55 class Document {
56     Document();
57     ...
58 };
59
60 namespace NestedNamespace {
61     ...
62 }
63
64 } // namespace WebCore
65
66 // Document.cpp
67 namespace WebCore {
68
69 Document::Document()
70 {
71     ...
72 }
73
74 } // namespace WebCore
75 </pre>
76
77 <h4 class="wrong">Wrong:</h4>
78 <pre class="code">
79 // Document.h
80 namespace WebCore {
81
82     class Document {
83         Document();
84         ...
85     };
86
87     namespace NestedNamespace {
88     ...
89     }
90
91 } // namespace WebCore
92
93 // Document.cpp
94 namespace WebCore {
95
96     Document::Document()
97     {
98         ...
99     }
100
101 } // namespace WebCore
102 </pre>
103 </li>
104
105 <li>A case label should line up with its switch statement.  The case statement is indented.
106 <h4 class="right">Right:</h4>
107 <pre class="code">
108 switch (condition) {
109 case fooCondition:
110 case barCondition:
111     i++;
112     break;
113 default:
114     i--;
115 }
116 </pre>
117
118 <h4 class="wrong">Wrong:</h4>
119 <pre class="code">
120 switch (condition) {
121     case fooCondition:
122     case barCondition:
123         i++;
124         break;
125     default:
126         i--;
127 }
128 </pre>
129 </li>
130
131 <li>Boolean expressions at the same nesting level that span multiple lines should
132 have their operators on the left side of the line instead of the right side.
133
134 <h4 class="right">Right:</h4>
135 <pre class="code">
136 if (attr->name() == srcAttr
137     || attr->name() == lowsrcAttr
138     || (attr->name() == usemapAttr && attr->value().domString()[0] != '#'))
139     return;
140 </pre>
141
142 <h4 class="wrong">Wrong:</h4>
143 <pre class="code">
144 if (attr->name() == srcAttr ||
145     attr->name() == lowsrcAttr ||
146     (attr->name() == usemapAttr && attr->value().domString()[0] != '#'))
147     return;
148 </pre>
149 </li>
150
151 </ol>
152
153 <h3>Spacing</h3>
154 <ol>
155 <li>Do not place spaces around unary operators.
156 <h4 class="right">Right:</h4>
157 <pre class="code">
158 i++;
159 </pre>
160
161 <h4 class="wrong">Wrong:</h4>
162 <pre class="code">
163 i ++;
164 </pre>
165 </li>
166
167 <li><em>Do</em> place spaces around binary and ternary operators.
168 <h4 class="right">Right:</h4>
169 <pre class="code">
170 y = m * x + b;
171 f(a, b);
172 c = a | b;
173 return condition ? 1 : 0;
174 </pre>
175
176 <h4 class="wrong">Wrong:</h4>
177 <pre class="code">
178 y=m*x+b;
179 f(a,b);
180 c = a|b;
181 return condition ? 1:0;
182 </pre>
183 </li>
184
185 <li>Do not place spaces before comma and semicolon.
186 <h4 class="right">Right:</h4>
187 <pre class="code">
188 for (int i = 0; i &lt; 10; i++)
189     doSomething();
190
191 f(a, b);
192 </pre>
193
194 <h4 class="wrong">Wrong:</h4>
195 <pre class="code">
196 for (int i = 0 ; i &lt; 10 ; i++)
197     doSomething();
198
199 f(a , b) ;
200 </pre>
201 </li>
202
203 <li>Place spaces between control statements and their parentheses.
204 <h4 class="right">Right:</h4>
205 <pre class="code">
206 if (condition)
207     doIt();
208 </pre>
209
210 <h4 class="wrong">Wrong:</h4>
211 <pre class="code">
212 if(condition)
213     doIt();
214 </pre>
215 </li>
216
217 <li>Do not place spaces between a function and its parentheses, or between a parenthesis and its content.
218 <h4 class="right">Right:</h4>
219 <pre class="code">
220 f(a, b);
221 </pre>
222
223 <h4 class="wrong">Wrong:</h4>
224 <pre class="code">
225 f (a, b);
226 f( a, b );
227 </pre>
228 </li>
229 </ol>
230
231 <h3>Line breaking</h3>
232 <ol>
233 <li>Each statement should get its own line.
234 <h4 class="right">Right:</h4>
235 <pre class="code">
236 x++;
237 y++;
238 if (condition)
239     doIt();
240 </pre>
241
242 <h4 class="wrong">Wrong:</h4>
243 <pre class="code">
244 x++; y++;
245 if (condition) doIt();
246 </pre>
247 </li>
248
249 <li>An <code>else</code> statement should go on the same line as a preceding close brace if one is present,
250 else it should line up with the <code>if</code> statement.
251 <h4 class="right">Right:</h4>
252 <pre class="code">
253 if (condition) {
254     ...
255 } else {
256     ...
257 }
258
259 if (condition)
260     doSomething();
261 else
262     doSomethingElse();
263
264 if (condition)
265     doSomething();
266 else {
267     ...
268 }
269 </pre>
270
271 <h4 class="wrong">Wrong:</h4>
272 <pre class="code">
273 if (condition) {
274     ...
275 }
276 else {
277     ...
278 }
279
280 if (condition) doSomething(); else doSomethingElse();
281
282 if (condition) doSomething(); else {
283     ...
284 }
285 </pre>
286 </li>
287
288 <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.
289 <h4 class="right">Right:</h4>
290 <pre class="code">
291 if (condition) {
292     ...
293     return someValue;
294 }
295 if (condition) {
296     ...
297 }
298 </pre>
299
300 <h4 class="wrong">Wrong:</h4>
301 <pre class="code">
302 if (condition) {
303     ...
304     return someValue;
305 } else if (condition) {
306     ...
307 }
308 </pre>
309 </li>
310 </ol>
311
312 <h3>Braces</h3>
313 <ol>
314 <li> Function definitions: place each brace on its own line.
315
316 <h4 class="right">Right:</h4>
317 <pre class="code">
318 int main()
319 {
320     ...
321 }
322 </pre>
323
324 <h4 class="wrong">Wrong:</h4>
325 <pre class="code">
326 int main() {
327     ...
328 }
329 </pre>
330 </li>
331 <li> Other braces: place the open brace on the line preceding the code block; place the close brace on its own line.
332
333 <h4 class="right">Right:</h4>
334 <pre class="code">
335 class MyClass {
336     ...
337 };
338
339 namespace WebCore {
340     ...
341 }
342
343 for (int i = 0; i &lt; 10; i++) {
344     ...
345 }
346 </pre>
347
348 <h4 class="wrong">Wrong:</h4>
349 <pre class="code">
350 class MyClass 
351 {
352     ...
353 };
354 </pre>
355 <li>One-line control clauses should not use braces unless comments are included
356 or a single statement spans multiple lines.
357 <h4 class="right">Right:</h4>
358 <pre class="code">
359 if (condition)
360     doIt();
361
362 if (condition) {
363     // Some comment
364     doIt();
365 }
366
367 if (condition) {
368     myFunction(reallyLongParam1, reallyLongParam2, ...
369         reallyLongParam5);
370 }
371 </pre>
372
373 <h4 class="wrong">Wrong:</h4>
374 <pre class="code">
375 if (condition) {
376     doIt();
377 }
378
379 if (condition)
380     // Some comment
381     doIt();
382
383 if (condition)
384     myFunction(reallyLongParam1, reallyLongParam2, ...
385         reallyLongParam5);
386 </pre>
387 </li>
388
389 <li>Control clauses without a body should use empty braces:
390 <h4 class="right">Right:</h4>
391 <pre class="code">
392 for ( ; current; current = current->next) { }
393 </pre>
394
395 <h4 class="wrong">Wrong:</h4>
396 <pre class="code">
397 for ( ; current; current = current->next);
398 </pre>
399 </li>
400 </ol>
401
402 <h3>Null, false and 0</h3>
403 <ol>
404 <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>
405 <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>
406 <li>Tests for true/false, null/non-null, and zero/non-zero should all be done without equality comparisons.<br>
407
408 <h4 class="right">Right:</h4>
409 <pre class="code">
410 if (condition)
411     doIt();
412     
413 if (!ptr)
414     return;
415
416 if (!count)
417     return;
418 </pre>
419
420 <h4 class="wrong">Wrong:</h4>
421 <pre class="code">
422 if (condition == true)
423     doIt();
424     
425 if (ptr == NULL)
426     return;
427     
428 if (count == 0)
429     return;
430 </pre>
431 </li>
432 <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>
433 </ol>
434
435 <h3>Floating point literals</h3>
436 <ol>
437 <li>Unless required in order to force floating point math, do not append
438 <code>.0</code>, <code>.f</code> and <code>.0f</code> to floating point
439 literals.
440
441 <h4 class="right">Right:</h4>
442 <pre class="code">
443 const double duration = 60;
444
445 void setDiameter(float diameter)
446 {
447     radius = diameter / 2;
448 }
449
450 setDiameter(10);
451
452 const int framesPerSecond = 12;
453 double frameDuration = 1.0 / framesPerSecond;
454 </pre>
455
456 <h4 class="wrong">Wrong:</h4>
457 <pre class="code">
458 const double duration = 60.0;
459
460 void setDiameter(float diameter)
461 {
462     radius = diameter / 2.f;
463 }
464
465 setDiameter(10.f);
466
467 const int framesPerSecond = 12;
468 double frameDuration = 1 / framesPerSecond; // integer division
469 </pre>
470 </li>
471 </ol>
472
473 <h3>Names</h3>
474 <ol>
475 <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.
476 <h4 class="right">Right:</h4>
477 <pre class="code">
478 struct Data;
479 size_t bufferSize;
480 class HTMLDocument;
481 String mimeType();
482 </pre>
483
484 <h4 class="wrong">Wrong:</h4>
485 <pre class="code">
486 struct data;
487 size_t buffer_size;
488 class HtmlDocument;
489 String MIMEType();
490 </pre>
491 </li>
492
493 <li>Use full words, except in the rare case where an abbreviation would be more canonical and easier to understand.
494 <h4 class="right">Right:</h4>
495 <pre class="code">
496 size_t characterSize;
497 size_t length;
498 short tabIndex; // more canonical
499 </pre>
500
501 <h4 class="wrong">Wrong:</h4>
502 <pre class="code">
503 size_t charSize;
504 size_t len;
505 short tabulationIndex; // bizarre
506 </pre>
507 </li>
508
509 <li>Data members in C++ classes should be private.  Static data members should be prefixed by "s_".  Other data members should be prefixed by "m_".
510 <h4 class="right">Right:</h4>
511 <pre class="code">
512 class String {
513 public:
514     ...
515
516 private:
517     short m_length;
518 };
519 </pre>
520
521 <h4 class="wrong">Wrong:</h4>
522 <pre class="code">
523 class String {
524 public:
525     ...
526
527     short length;
528 };
529 </pre>
530 </li>
531
532 <li>Prefix Objective-C instance variables with "_".
533 <h4 class="right">Right:</h4>
534 <pre class="code">
535 @class String
536     ...
537     short _length;
538 @end
539 </pre>
540
541 <h4 class="wrong">Wrong:</h4>
542 <pre class="code">
543 @class String
544     ...
545     short length;
546 @end
547 </pre>
548 </li>
549
550 <li>Precede boolean values with words like "is" and "did".
551 <h4 class="right">Right:</h4>
552 <pre class="code">
553 bool isValid;
554 bool didSendData;
555 </pre>
556
557 <h4 class="wrong">Wrong:</h4>
558 <pre class="code">
559 bool valid;
560 bool sentData;
561 </pre>
562 </li>
563
564 <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.
565 <h4 class="right">Right:</h4>
566 <pre class="code">
567 void setCount(size_t); // sets m_count
568 size_t count(); // returns m_count
569 </pre>
570
571 <h4 class="wrong">Wrong:</h4>
572 <pre class="code">
573 void setCount(size_t); // sets m_theCount
574 size_t getCount();
575 </pre>
576 </li>
577
578 <li>Use descriptive verbs in function names.
579 <h4 class="right">Right:</h4>
580 <pre class="code">
581 bool convertToASCII(short*, size_t);
582 </pre>
583
584 <h4 class="wrong">Wrong:</h4>
585 <pre class="code">
586 bool toASCII(short*, size_t);
587 </pre>
588 </li>
589
590 <li>Leave meaningless variable names out of function declarations.
591 <h4 class="right">Right:</h4>
592 <pre class="code">
593 void setCount(size_t);
594 </pre>
595
596 <h4 class="wrong">Wrong:</h4>
597 <pre class="code">
598 void setCount(size_t count);
599 </pre>
600 </li>
601
602 <li>Objective-C method names should follow the Cocoa naming guidelines &mdash;
603 they should read like a phrase and each piece of the selector should 
604 start with a lowercase letter and use intercaps.</li>
605 <li>Enum members should user InterCaps with an initial capital letter.</li>
606 <li>Prefer const to #define. Prefer inline functions to macros.</li>
607 <li>#defined constants should use all uppercase names with words separated by underscores.</li>
608 <li> Macros that expand to function calls or other non-constant computation: these 
609 should be named like functions, and should have parentheses at the end, even if 
610 they take no arguments (with the exception of some special macros like ASSERT). 
611 Note that usually it is preferable to use an inline function in such cases instead of a macro.<br>
612
613 <h4 class="right">Right:</h4>
614 <pre class="code">
615 #define WBStopButtonTitle() \
616         NSLocalizedString(@"Stop", @"Stop button title")
617 </pre>
618
619 <h4 class="wrong">Wrong:</h4>
620 <pre class="code">
621 #define WB_STOP_BUTTON_TITLE \
622         NSLocalizedString(@"Stop", @"Stop button title")
623
624 #define WBStopButtontitle \
625         NSLocalizedString(@"Stop", @"Stop button title")
626 </pre>
627 </li>
628 <li>#define, #ifdef "header guards" should be named exactly the same as the file (including case), replacing the '.' with a '_'.
629 <h4 class="right">Right:</h4>
630 <pre class="code">
631 // HTMLDocument.h
632 #ifndef HTMLDocument_h
633 #define HTMLDocument_h
634 </pre>
635
636 <h4 class="wrong">Wrong:</h4>
637 <pre class="code">
638 // HTMLDocument.h
639 #ifndef _HTML_DOCUMENT_H_
640 #define _HTML_DOCUMENT_H_
641 </pre>
642 </li>
643 </ol>
644
645 <h3>Other Punctuation</h3>
646
647 <ol>
648
649 <li>Constructors for C++ classes should initialize all of their members using C++ 
650 initializer syntax.  Each member (and superclass) should be indented on a separate 
651 line, with the colon or comma preceding the member on that line.
652
653 <h4 class="right">Right:</h4>
654 <pre class="code">
655 MyClass::MyClass(Document* doc)
656     : MySuperClass()
657     , m_myMember(0)
658     , m_doc(doc)
659 {
660 }
661
662 MyOtherClass::MyOtherClass()
663     : MySuperClass()
664 {
665 }
666 </pre>
667
668 <h4 class="wrong">Wrong:</h4>
669 <pre class="code">
670 MyClass::MyClass(Document* doc) : MySuperClass()
671 {
672     m_myMember = 0;
673     m_doc = doc;
674 }
675
676 MyOtherClass::MyOtherClass() : MySuperClass() {}
677 </pre>
678
679 <li>Pointer types in non-C++ code &mdash; Pointer types should be written with a space between the
680 type and the * (so the * is adjacent to the following identifier if any).
681
682 <li>Pointer and reference types in C++ code &mdash; Both pointer types and reference types
683 should be written with no space between the type name and the * or &amp;.
684
685 <h4 class="right">Right:</h4>
686 <pre class="code">
687 Image* SVGStyledElement::doSomething(PaintInfo&amp; paintInfo)
688 {
689     SVGStyledElement* element = static_cast&lt;SVGStyledElement*>(node());
690     const KCDashArray&amp; dashes = dashArray();
691 </pre>
692
693 <h4 class="wrong">Wrong:</h4>
694 <pre class="code">
695 Image *SVGStyledElement::doSomething(PaintInfo &amp;paintInfo)
696 {
697     SVGStyledElement *element = static_cast&lt;SVGStyledElement *>(node());
698     const KCDashArray &amp;dashes = dashArray();
699 </pre>
700
701 </ol>
702
703 <h3>#include Statements</h3>
704
705 <ol>
706
707 <li>All implementation files must #include "config.h" first. Header
708 files should never include "config.h".
709
710 <h4 class="right">Right:</h4>
711 <pre class="code">
712 // RenderLayer.h
713 #include "Node.h"
714 #include "RenderObject.h"
715 #include "RenderView.h"
716 </pre>
717
718 <h4 class="wrong">Wrong:</h4>
719 <pre class="code">
720 // RenderLayer.h
721 #include "config.h"
722
723 #include "RenderObject.h"
724 #include "RenderView.h"
725 #include "Node.h"
726 </pre>
727
728 <li>All implementation files must #include the primary header second,
729 just after "config.h". So for example, Node.cpp should include Node.h first,
730 before other files. This guarantees that each header's completeness is tested.
731 This also assures that each header can be compiled without requiring any other
732 header files be included first.
733
734 <li>Other #include statements should be in sorted order (case sensitive, as
735 done by the command-line sort tool or the Xcode sort selection command).
736 Don't bother to organize them in a logical order.
737
738 <h4 class="right">Right:</h4>
739 <pre class="code">
740 // HTMLDivElement.cpp
741 #include "config.h"
742 #include "HTMLDivElement.h"
743
744 #include "Attribute.h"
745 #include "HTMLElement.h"
746 #include "QualifiedName.h"
747
748 </pre>
749
750 <h4 class="wrong">Wrong:</h4>
751 <pre class="code">
752 // HTMLDivElement.cpp
753 #include "HTMLElement.h"
754 #include "HTMLDivElement.h"
755 #include "QualifiedName.h"
756 #include "Attribute.h"
757 </pre>
758
759 <li>Includes of system headers must come after includes of other headers.
760
761 <h4 class="right">Right:</h4>
762 <pre class="code">
763 // ConnectionQt.cpp
764 #include "ArgumentEncoder.h"
765 #include "ProcessLauncher.h"
766 #include "WebPageProxyMessageKinds.h"
767 #include "WorkItem.h"
768 #include &ltQApplication&gt
769 #include &ltQLocalServer&gt
770 #include &ltQLocalSocket&gt
771 </pre>
772
773 <h4 class="wrong">Wrong:</h4>
774 <pre class="code">
775 // ConnectionQt.cpp
776 #include "ArgumentEncoder.h"
777 #include "ProcessLauncher.h"
778 #include &ltQApplication&gt
779 #include &ltQLocalServer&gt
780 #include &ltQLocalSocket&gt
781 #include "WebPageProxyMessageKinds.h"
782 #include "WorkItem.h"
783 </pre>
784 </li>
785 </ol>
786
787 <h3>"using" Statements</h3>
788
789 <ol>
790
791 <li>In header files, do not use "using" statements in namespace
792 (or global) scope.
793
794 <h4 class="right">Right:</h4>
795 <pre class="code">
796 // wtf/Vector.h
797
798 namespace WTF {
799
800 class VectorBuffer {
801     using std::min;
802     ...
803 };
804
805 } // namespace WTF
806 </pre>
807 <h4 class="wrong">Wrong:</h4>
808 <pre class="code">
809 // wtf/Vector.h
810
811 namespace WTF {
812
813 using std::min;
814     
815 class VectorBuffer {
816     ...
817 };
818
819 } // namespace WTF
820 </pre>
821 </li>
822
823 <li>In header files in the WTF sub-library, however, it is acceptable
824 to use "using" declarations at the end of the file to import one
825 or more names in the WTF namespace into the global scope.
826
827 <h4 class="right">Right:</h4>
828 <pre class="code">
829 // wtf/Vector.h
830
831 namespace WTF {
832
833 } // namespace WTF
834
835 using WTF::Vector;
836 </pre>
837 <h4 class="wrong">Wrong:</h4>
838 <pre class="code">
839 // wtf/Vector.h
840
841 namespace WTF {
842
843 } // namespace WTF
844
845 using namespace WTF;
846 </pre>
847 <h4 class="wrong">Wrong:</h4>
848 <pre class="code">
849 // runtime/UString.h
850
851 namespace WTF {
852
853 } // namespace WTF
854
855 using WTF::PlacementNewAdopt;
856 </pre>
857 </li>
858
859 <li>In C++ implementation files, do not use statements of the form
860 "using std::foo" to import names in the standard template library.
861 Use "using namespace std" instead.
862
863 <h4 class="right">Right:</h4>
864 <pre class="code">
865 // HTMLBaseElement.cpp
866
867 using namespace std;
868
869 namespace WebCore {
870
871 } // namespace WebCore
872 </pre>
873
874 <h4 class="wrong">Wrong:</h4>
875 <pre class="code">
876 // HTMLBaseElement.cpp
877
878 using std::swap;
879
880 namespace WebCore {
881
882 } // namespace WebCore
883 </pre>
884 </li>
885
886 <li>In implementation files, if a "using namespace" statement is
887 for a nested namespace whose parent namespace is defined in the file,
888 put the statement inside that namespace definition.
889
890 <h4 class="right">Right:</h4>
891 <pre class="code">
892 // HTMLBaseElement.cpp
893
894 namespace WebCore {
895
896 using namespace HTMLNames;
897
898 } // namespace WebCore
899 </pre>
900
901 <h4 class="wrong">Wrong:</h4>
902 <pre class="code">
903 // HTMLBaseElement.cpp
904
905 using namespace WebCore::HTMLNames;
906
907 namespace WebCore {
908
909 } // namespace WebCore
910 </pre>
911 </li>
912
913 <li>In implementation files, put all other "using" statements
914 at the beginning of the file, before any namespace definitions and
915 after any "include" statements.
916
917 <h4 class="right">Right:</h4>
918 <pre class="code">
919 // HTMLSelectElement.cpp
920
921 using namespace std;
922
923 namespace WebCore {
924
925 } // namespace WebCore
926 </pre>
927
928 <h4 class="wrong">Wrong:</h4>
929 <pre class="code">
930 // HTMLSelectElement.cpp
931
932 namespace WebCore {
933
934 using namespace std;
935
936 } // namespace WebCore
937 </pre>
938 </li>
939
940 </ol>
941
942 <?php
943     include("../footer.inc");
944 ?>