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