86f8d3680f6903301eafe595864ba6f30e09233b
[WebKit-https.git] / Websites / webkit.org / 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
18 .idbutton {
19   color: #888;
20   font-size: smaller;
21   cursor: pointer;
22 }
23 </style>
24
25
26 END;
27
28     include("../header.inc"); 
29 ?>
30
31 <h2>WebKit Coding Style Guidelines</h2>
32 <h3 id="indentation">Indentation</h3>
33
34 <ol>
35 <li id="indentation-no-tabs"> Use spaces, not tabs. Tabs should only appear in files that require them for semantic meaning, like Makefiles.
36 </li>
37 <li id="indentation-4-spaces"> The indent size is 4 spaces.
38 <h4 class="right">Right:</h4>
39 <pre class="code">
40 int main()
41 {
42     return 0;
43 }
44 </pre>
45
46 <h4 class="wrong">Wrong:</h4>
47 <pre class="code">
48 int main() 
49 {
50         return 0;
51 }
52 </pre>
53 </li>
54 <li id="indentation-namespace">The contents of an outermost <code>namespace</code> block (and any nested namespaces with the same scope)
55 should not be indented. The contents of other nested namespaces should be indented.
56 <h4 class="right">Right:</h4>
57 <pre class="code">
58 // Document.h
59 namespace WebCore {
60
61 class Document {
62     Document();
63     ...
64 };
65
66 namespace NestedNamespace {
67     ...
68 }
69
70 } // namespace WebCore
71
72 // Document.cpp
73 namespace WebCore {
74
75 Document::Document()
76 {
77     ...
78 }
79
80 } // namespace WebCore
81 </pre>
82
83 <h4 class="wrong">Wrong:</h4>
84 <pre class="code">
85 // Document.h
86 namespace WebCore {
87
88     class Document {
89         Document();
90         ...
91     };
92
93     namespace NestedNamespace {
94     ...
95     }
96
97 } // namespace WebCore
98
99 // Document.cpp
100 namespace WebCore {
101
102     Document::Document()
103     {
104         ...
105     }
106
107 } // namespace WebCore
108 </pre>
109 </li>
110
111 <li id="indentation-case-label">A case label should line up with its switch statement.  The case statement is indented.
112 <h4 class="right">Right:</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
124 <h4 class="wrong">Wrong:</h4>
125 <pre class="code">
126 switch (condition) {
127     case fooCondition:
128     case barCondition:
129         i++;
130         break;
131     default:
132         i--;
133 }
134 </pre>
135 </li>
136
137 <li id="indentation-wrap-bool-op">Boolean expressions at the same nesting level that span multiple lines should
138 have their operators on the left side of the line instead of the right side.
139
140 <h4 class="right">Right:</h4>
141 <pre class="code">
142 if (attr->name() == srcAttr
143     || attr->name() == lowsrcAttr
144     || (attr->name() == usemapAttr && attr->value().domString()[0] != '#'))
145     return;
146 </pre>
147
148 <h4 class="wrong">Wrong:</h4>
149 <pre class="code">
150 if (attr->name() == srcAttr ||
151     attr->name() == lowsrcAttr ||
152     (attr->name() == usemapAttr && attr->value().domString()[0] != '#'))
153     return;
154 </pre>
155 </li>
156
157 </ol>
158
159 <h3 id="spacing">Spacing</h3>
160 <ol>
161 <li id="spacing-unary-op">Do not place spaces around unary operators.
162 <h4 class="right">Right:</h4>
163 <pre class="code">
164 i++;
165 </pre>
166
167 <h4 class="wrong">Wrong:</h4>
168 <pre class="code">
169 i ++;
170 </pre>
171 </li>
172
173 <li id="spacing-binary-ternary-op"><em>Do</em> place spaces around binary and ternary operators.
174 <h4 class="right">Right:</h4>
175 <pre class="code">
176 y = m * x + b;
177 f(a, b);
178 c = a | b;
179 return condition ? 1 : 0;
180 </pre>
181
182 <h4 class="wrong">Wrong:</h4>
183 <pre class="code">
184 y=m*x+b;
185 f(a,b);
186 c = a|b;
187 return condition ? 1:0;
188 </pre>
189 </li>
190
191 <li id="spacing-comma-semicolon">Do not place spaces before comma and semicolon.
192 <h4 class="right">Right:</h4>
193 <pre class="code">
194 for (int i = 0; i &lt; 10; ++i)
195     doSomething();
196
197 f(a, b);
198 </pre>
199
200 <h4 class="wrong">Wrong:</h4>
201 <pre class="code">
202 for (int i = 0 ; i &lt; 10 ; ++i)
203     doSomething();
204
205 f(a , b) ;
206 </pre>
207 </li>
208
209 <li id="spacing-control-paren">Place spaces between control statements and their parentheses.
210 <h4 class="right">Right:</h4>
211 <pre class="code">
212 if (condition)
213     doIt();
214 </pre>
215
216 <h4 class="wrong">Wrong:</h4>
217 <pre class="code">
218 if(condition)
219     doIt();
220 </pre>
221 </li>
222
223 <li id="spacing-function-paren">Do not place spaces between a function and its parentheses, or between a parenthesis and its content.
224 <h4 class="right">Right:</h4>
225 <pre class="code">
226 f(a, b);
227 </pre>
228
229 <h4 class="wrong">Wrong:</h4>
230 <pre class="code">
231 f (a, b);
232 f( a, b );
233 </pre>
234 </li>
235 </ol>
236
237 <h3 id="linebreaking">Line breaking</h3>
238 <ol>
239 <li id="linebreaking-multiple-statements">Each statement should get its own line.
240 <h4 class="right">Right:</h4>
241 <pre class="code">
242 x++;
243 y++;
244 if (condition)
245     doIt();
246 </pre>
247
248 <h4 class="wrong">Wrong:</h4>
249 <pre class="code">
250 x++; y++;
251 if (condition) doIt();
252 </pre>
253 </li>
254
255 <li id="linebreaking-else-braces">An <code>else</code> statement should go on the same line as a preceding close brace if one is present,
256 else it should line up with the <code>if</code> statement.
257 <h4 class="right">Right:</h4>
258 <pre class="code">
259 if (condition) {
260     ...
261 } else {
262     ...
263 }
264
265 if (condition)
266     doSomething();
267 else
268     doSomethingElse();
269
270 if (condition)
271     doSomething();
272 else {
273     ...
274 }
275 </pre>
276
277 <h4 class="wrong">Wrong:</h4>
278 <pre class="code">
279 if (condition) {
280     ...
281 }
282 else {
283     ...
284 }
285
286 if (condition) doSomething(); else doSomethingElse();
287
288 if (condition) doSomething(); else {
289     ...
290 }
291 </pre>
292 </li>
293
294 <li id="linebreaking-else-if">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.
295 <h4 class="right">Right:</h4>
296 <pre class="code">
297 if (condition) {
298     ...
299     return someValue;
300 }
301 if (condition) {
302     ...
303 }
304 </pre>
305
306 <h4 class="wrong">Wrong:</h4>
307 <pre class="code">
308 if (condition) {
309     ...
310     return someValue;
311 } else if (condition) {
312     ...
313 }
314 </pre>
315 </li>
316 </ol>
317
318 <h3 id="braces">Braces</h3>
319 <ol>
320 <li id="braces-function"> Function definitions: place each brace on its own line.
321
322 <h4 class="right">Right:</h4>
323 <pre class="code">
324 int main()
325 {
326     ...
327 }
328 </pre>
329
330 <h4 class="wrong">Wrong:</h4>
331 <pre class="code">
332 int main() {
333     ...
334 }
335 </pre>
336 </li>
337 <li id="braces-blocks"> Other braces: place the open brace on the line preceding the code block; place the close brace on its own line.
338
339 <h4 class="right">Right:</h4>
340 <pre class="code">
341 class MyClass {
342     ...
343 };
344
345 namespace WebCore {
346     ...
347 }
348
349 for (int i = 0; i &lt; 10; ++i) {
350     ...
351 }
352 </pre>
353
354 <h4 class="wrong">Wrong:</h4>
355 <pre class="code">
356 class MyClass 
357 {
358     ...
359 };
360 </pre>
361 <li id="braces-one-line">One-line control clauses should not use braces unless comments are included
362 or a single statement spans multiple lines.
363 <h4 class="right">Right:</h4>
364 <pre class="code">
365 if (condition)
366     doIt();
367
368 if (condition) {
369     // Some comment
370     doIt();
371 }
372
373 if (condition) {
374     myFunction(reallyLongParam1, reallyLongParam2, ...
375         reallyLongParam5);
376 }
377 </pre>
378
379 <h4 class="wrong">Wrong:</h4>
380 <pre class="code">
381 if (condition) {
382     doIt();
383 }
384
385 if (condition)
386     // Some comment
387     doIt();
388
389 if (condition)
390     myFunction(reallyLongParam1, reallyLongParam2, ...
391         reallyLongParam5);
392 </pre>
393 </li>
394
395 <li id="braces-empty-block">Control clauses without a body should use empty braces:
396 <h4 class="right">Right:</h4>
397 <pre class="code">
398 for ( ; current; current = current->next) { }
399 </pre>
400
401 <h4 class="wrong">Wrong:</h4>
402 <pre class="code">
403 for ( ; current; current = current->next);
404 </pre>
405 </li>
406 </ol>
407
408 <h3 id="zero">Null, false and 0</h3>
409 <ol>
410 <li id="zero-null">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>
411
412 <li id="zero-bool">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>
413
414 <li id="zero-comparison">Tests for true/false, null/non-null, and zero/non-zero should all be done without equality comparisons.<br>
415
416 <h4 class="right">Right:</h4>
417 <pre class="code">
418 if (condition)
419     doIt();
420     
421 if (!ptr)
422     return;
423
424 if (!count)
425     return;
426 </pre>
427
428 <h4 class="wrong">Wrong:</h4>
429 <pre class="code">
430 if (condition == true)
431     doIt();
432     
433 if (ptr == NULL)
434     return;
435     
436 if (count == 0)
437     return;
438 </pre>
439 </li>
440
441 <li id="zero-objc-variables">In Objective-C, instance variables are initialized to zero automatically. Don't add explicit initializations to nil or NO in an init method.</li>
442 </ol>
443
444 <h3 id="float">Floating point literals</h3>
445 <ol>
446 <li id="float-suffixes">Unless required in order to force floating point math, do not append
447 <code>.0</code>, <code>.f</code> and <code>.0f</code> to floating point
448 literals.
449
450 <h4 class="right">Right:</h4>
451 <pre class="code">
452 const double duration = 60;
453
454 void setDiameter(float diameter)
455 {
456     radius = diameter / 2;
457 }
458
459 setDiameter(10);
460
461 const int framesPerSecond = 12;
462 double frameDuration = 1.0 / framesPerSecond;
463 </pre>
464
465 <h4 class="wrong">Wrong:</h4>
466 <pre class="code">
467 const double duration = 60.0;
468
469 void setDiameter(float diameter)
470 {
471     radius = diameter / 2.f;
472 }
473
474 setDiameter(10.f);
475
476 const int framesPerSecond = 12;
477 double frameDuration = 1 / framesPerSecond; // integer division
478 </pre>
479 </li>
480 </ol>
481
482 <h3 id="names">Names</h3>
483 <ol>
484 <li id="names-basic">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.
485 <h4 class="right">Right:</h4>
486 <pre class="code">
487 struct Data;
488 size_t bufferSize;
489 class HTMLDocument;
490 String mimeType();
491 </pre>
492
493 <h4 class="wrong">Wrong:</h4>
494 <pre class="code">
495 struct data;
496 size_t buffer_size;
497 class HtmlDocument;
498 String MIMEType();
499 </pre>
500 </li>
501
502 <li id="names-full-words">Use full words, except in the rare case where an abbreviation would be more canonical and easier to understand.
503 <h4 class="right">Right:</h4>
504 <pre class="code">
505 size_t characterSize;
506 size_t length;
507 short tabIndex; // more canonical
508 </pre>
509
510 <h4 class="wrong">Wrong:</h4>
511 <pre class="code">
512 size_t charSize;
513 size_t len;
514 short tabulationIndex; // bizarre
515 </pre>
516 </li>
517
518 <li id="names-data-members">Data members in C++ classes should be private.  Static data members should be prefixed by "s_".  Other data members should be prefixed by "m_".
519 <h4 class="right">Right:</h4>
520 <pre class="code">
521 class String {
522 public:
523     ...
524
525 private:
526     short m_length;
527 };
528 </pre>
529
530 <h4 class="wrong">Wrong:</h4>
531 <pre class="code">
532 class String {
533 public:
534     ...
535
536     short length;
537 };
538 </pre>
539 </li>
540
541 <li id="names-objc-instance-variables">Prefix Objective-C instance variables with "_".
542 <h4 class="right">Right:</h4>
543 <pre class="code">
544 @class String
545     ...
546     short _length;
547 @end
548 </pre>
549
550 <h4 class="wrong">Wrong:</h4>
551 <pre class="code">
552 @class String
553     ...
554     short length;
555 @end
556 </pre>
557 </li>
558
559 <li id="names-bool">Precede boolean values with words like "is" and "did".
560 <h4 class="right">Right:</h4>
561 <pre class="code">
562 bool isValid;
563 bool didSendData;
564 </pre>
565
566 <h4 class="wrong">Wrong:</h4>
567 <pre class="code">
568 bool valid;
569 bool sentData;
570 </pre>
571 </li>
572
573 <li id="names-setter-getter">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.
574 <h4 class="right">Right:</h4>
575 <pre class="code">
576 void setCount(size_t); // sets m_count
577 size_t count(); // returns m_count
578 </pre>
579
580 <h4 class="wrong">Wrong:</h4>
581 <pre class="code">
582 void setCount(size_t); // sets m_theCount
583 size_t getCount();
584 </pre>
585 </li>
586
587 <li id="names-out-argument">Precede getters that return values through out arguments with the word "get".
588 <h4 class="right">Right:</h4>
589 <pre class="code">
590 void getInlineBoxAndOffset(InlineBox*&amp;, int&amp; caretOffset) const;
591 </pre>
592
593 <h4 class="wrong">Wrong:</h4>
594 <pre class="code">
595 void inlineBoxAndOffset(InlineBox*&amp;, int&amp; caretOffset) const;
596 </pre>
597 </li>
598
599 <li id="names-verb">Use descriptive verbs in function names.
600 <h4 class="right">Right:</h4>
601 <pre class="code">
602 bool convertToASCII(short*, size_t);
603 </pre>
604
605 <h4 class="wrong">Wrong:</h4>
606 <pre class="code">
607 bool toASCII(short*, size_t);
608 </pre>
609 </li>
610
611 <li id="names-variable-name-in-function-decl">Leave meaningless variable names out of function declarations. A good rule of thumb is if the parameter type name contains the parameter name (without trailing numbers or pluralization), then the parameter name isn't needed.  Usually, there should be a parameter name for bools, strings, and numerical types.
612 <h4 class="right">Right:</h4>
613 <pre class="code">
614 void setCount(size_t);
615
616 void doSomething(ScriptExecutionContext*);
617 </pre>
618
619 <h4 class="wrong">Wrong:</h4>
620 <pre class="code">
621 void setCount(size_t count);
622
623 void doSomething(ScriptExecutionContext* context);
624 </pre>
625 </li>
626
627 <li id="names-enum-to-bool">Prefer enums to bools on function parameters if callers are likely to be
628 passing constants, since named constants are easier to read at the call
629 site.  An exception to this rule is a setter function, where the name of the
630 function already makes clear what the boolean is.
631 <h4 class="right">Right:</h4>
632 <pre class="code">
633 doSomething(something, AllowFooBar);
634 paintTextWithShadows(context, ..., textStrokeWidth > 0, isHorizontal());
635 setResizable(false);
636 </pre>
637
638 <h4 class="wrong">Wrong:</h4>
639 <pre class="code">
640 doSomething(something, false);
641 setResizable(NotResizable);
642 </pre>
643 </li>
644
645 <li id="names-objc-methods">Objective-C method names should follow the Cocoa naming guidelines &mdash;
646 they should read like a phrase and each piece of the selector should 
647 start with a lowercase letter and use intercaps.</li>
648
649 <li id="names-enum-members">Enum members should use InterCaps with an initial capital letter.</li>
650
651 <li id="names-const-to-define">Prefer const to #define. Prefer inline functions to macros.</li>
652
653 <li id="names-define-constants">#defined constants should use all uppercase names with words separated by underscores.</li>
654
655 <li id="names-define-non-const"> Macros that expand to function calls or other non-constant computation: these
656 should be named like functions, and should have parentheses at the end, even if 
657 they take no arguments (with the exception of some special macros like ASSERT). 
658 Note that usually it is preferable to use an inline function in such cases instead of a macro.<br>
659
660 <h4 class="right">Right:</h4>
661 <pre class="code">
662 #define WBStopButtonTitle() \
663         NSLocalizedString(@"Stop", @"Stop button title")
664 </pre>
665
666 <h4 class="wrong">Wrong:</h4>
667 <pre class="code">
668 #define WB_STOP_BUTTON_TITLE \
669         NSLocalizedString(@"Stop", @"Stop button title")
670
671 #define WBStopButtontitle \
672         NSLocalizedString(@"Stop", @"Stop button title")
673 </pre>
674 </li>
675
676 <li id="names-header-guards">#define, #ifdef "header guards" should be named exactly the same as the file (including case), replacing the '.' with a '_'.
677 <h4 class="right">Right:</h4>
678 <pre class="code">
679 // HTMLDocument.h
680 #ifndef HTMLDocument_h
681 #define HTMLDocument_h
682 </pre>
683
684 <h4 class="wrong">Wrong:</h4>
685 <pre class="code">
686 // HTMLDocument.h
687 #ifndef _HTML_DOCUMENT_H_
688 #define _HTML_DOCUMENT_H_
689 </pre>
690 </li>
691 </ol>
692
693 <h3 id="punctuation">Other Punctuation</h3>
694
695 <ol>
696
697 <li id="punctuation-member-init">Constructors for C++ classes should initialize all of their members using C++ 
698 initializer syntax.  Each member (and superclass) should be indented on a separate 
699 line, with the colon or comma preceding the member on that line.
700
701 <h4 class="right">Right:</h4>
702 <pre class="code">
703 MyClass::MyClass(Document* doc)
704     : MySuperClass()
705     , m_myMember(0)
706     , m_doc(doc)
707 {
708 }
709
710 MyOtherClass::MyOtherClass()
711     : MySuperClass()
712 {
713 }
714 </pre>
715
716 <h4 class="wrong">Wrong:</h4>
717 <pre class="code">
718 MyClass::MyClass(Document* doc) : MySuperClass()
719 {
720     m_myMember = 0;
721     m_doc = doc;
722 }
723
724 MyOtherClass::MyOtherClass() : MySuperClass() {}
725 </pre>
726
727 <li id="punctuation-vector-index">Prefer index over iterator in Vector iterations for a terse, easier-to-read code.
728
729 <h4 class="right">Right:</h4>
730 <pre class="code">
731 size_t frameViewsCount = frameViews.size();
732 for (size_t i = 0; i &lt; frameViewsCount; ++i)
733     frameViews[i]->updateLayoutAndStyleIfNeededRecursive();
734 </pre>
735
736 <h4 class="wrong">Wrong:</h4>
737 <pre class="code">
738 const Vector&lt;RefPtr&lt;FrameView&gt; &gt;::iterator end = frameViews.end();
739 for (Vector&lt;RefPtr&lt;FrameView&gt; &gt;::iterator it = frameViews.begin(); it != end; ++it)
740     (*it)-&gt;updateLayoutAndStyleIfNeededRecursive();
741 </pre>
742 </ol>
743
744 <h3 id="pointers">Pointers and References</h3>
745
746 <ol>
747
748 <li id="pointers-non-cpp">Pointer types in non-C++ code &mdash; Pointer types should be written with a space between the
749 type and the * (so the * is adjacent to the following identifier if any).
750
751 <li id="pointers-cpp">Pointer and reference types in C++ code &mdash; Both pointer types and reference types
752 should be written with no space between the type name and the * or &amp;.
753
754 <h4 class="right">Right:</h4>
755 <pre class="code">
756 Image* SVGStyledElement::doSomething(PaintInfo&amp; paintInfo)
757 {
758     SVGStyledElement* element = static_cast&lt;SVGStyledElement*>(node());
759     const KCDashArray&amp; dashes = dashArray();
760 </pre>
761
762 <h4 class="wrong">Wrong:</h4>
763 <pre class="code">
764 Image *SVGStyledElement::doSomething(PaintInfo &amp;paintInfo)
765 {
766     SVGStyledElement *element = static_cast&lt;SVGStyledElement *>(node());
767     const KCDashArray &amp;dashes = dashArray();
768 </pre>
769
770 <li id="pointers-out-argument">An out argument of a function should be passed by reference except rare cases where
771 it is optional in which case it should be passed by pointer.
772
773 <h4 class="right">Right:</h4>
774 <pre class="code">
775 void MyClass::getSomeValue(OutArgumentType&amp; outArgument) const
776 {
777     outArgument = m_value;
778 }
779
780 void MyClass::doSomething(OutArgumentType* outArgument) const
781 {
782     doSomething();
783     if (outArgument)
784         *outArgument = m_value;
785 }
786 </pre>
787
788 <h4 class="wrong">Wrong:</h4>
789 <pre class="code">
790 void MyClass::getSomeValue(OutArgumentType* outArgument) const
791 {
792     *outArgument = m_value;
793 }
794 </pre>
795
796 </ol>
797
798 <h3 id="include">#include Statements</h3>
799
800 <ol>
801
802 <li id="include-config-h">All implementation files must #include "config.h" first. Header
803 files should never include "config.h".
804
805 <h4 class="right">Right:</h4>
806 <pre class="code">
807 // RenderLayer.h
808 #include "Node.h"
809 #include "RenderObject.h"
810 #include "RenderView.h"
811 </pre>
812
813 <h4 class="wrong">Wrong:</h4>
814 <pre class="code">
815 // RenderLayer.h
816 #include "config.h"
817
818 #include "RenderObject.h"
819 #include "RenderView.h"
820 #include "Node.h"
821 </pre>
822
823 <li id="include-primary">All implementation files must #include the primary header second,
824 just after "config.h". So for example, Node.cpp should include Node.h first,
825 before other files. This guarantees that each header's completeness is tested.
826 This also assures that each header can be compiled without requiring any other
827 header files be included first.
828
829 <li id="include-others">Other #include statements should be in sorted order (case sensitive, as
830 done by the command-line sort tool or the Xcode sort selection command).
831 Don't bother to organize them in a logical order.
832
833 <h4 class="right">Right:</h4>
834 <pre class="code">
835 // HTMLDivElement.cpp
836 #include "config.h"
837 #include "HTMLDivElement.h"
838
839 #include "Attribute.h"
840 #include "HTMLElement.h"
841 #include "QualifiedName.h"
842
843 </pre>
844
845 <h4 class="wrong">Wrong:</h4>
846 <pre class="code">
847 // HTMLDivElement.cpp
848 #include "HTMLElement.h"
849 #include "HTMLDivElement.h"
850 #include "QualifiedName.h"
851 #include "Attribute.h"
852 </pre>
853
854 <li id="include-system">Includes of system headers must come after includes of other headers.
855
856 <h4 class="right">Right:</h4>
857 <pre class="code">
858 // ConnectionQt.cpp
859 #include "ArgumentEncoder.h"
860 #include "ProcessLauncher.h"
861 #include "WebPageProxyMessageKinds.h"
862 #include "WorkItem.h"
863 #include &lt;QApplication&gt;
864 #include &lt;QLocalServer&gt;
865 #include &lt;QLocalSocket&gt;
866 </pre>
867
868 <h4 class="wrong">Wrong:</h4>
869 <pre class="code">
870 // ConnectionQt.cpp
871 #include "ArgumentEncoder.h"
872 #include "ProcessLauncher.h"
873 #include &lt;QApplication&gt;
874 #include &lt;QLocalServer&gt;
875 #include &lt;QLocalSocket&gt;
876 #include "WebPageProxyMessageKinds.h"
877 #include "WorkItem.h"
878 </pre>
879 </li>
880 </ol>
881
882 <h3 id="using">"using" Statements</h3>
883
884 <ol>
885
886 <li id="using-in-headers">In header files, do not use "using" statements in namespace
887 (or global) scope.
888
889 <h4 class="right">Right:</h4>
890 <pre class="code">
891 // wtf/Vector.h
892
893 namespace WTF {
894
895 class VectorBuffer {
896     using std::min;
897     ...
898 };
899
900 } // namespace WTF
901 </pre>
902 <h4 class="wrong">Wrong:</h4>
903 <pre class="code">
904 // wtf/Vector.h
905
906 namespace WTF {
907
908 using std::min;
909     
910 class VectorBuffer {
911     ...
912 };
913
914 } // namespace WTF
915 </pre>
916 </li>
917
918 <li id="using-wtf">In header files in the WTF sub-library, however, it is acceptable
919 to use "using" declarations at the end of the file to import one
920 or more names in the WTF namespace into the global scope.
921
922 <h4 class="right">Right:</h4>
923 <pre class="code">
924 // wtf/Vector.h
925
926 namespace WTF {
927
928 } // namespace WTF
929
930 using WTF::Vector;
931 </pre>
932 <h4 class="wrong">Wrong:</h4>
933 <pre class="code">
934 // wtf/Vector.h
935
936 namespace WTF {
937
938 } // namespace WTF
939
940 using namespace WTF;
941 </pre>
942 <h4 class="wrong">Wrong:</h4>
943 <pre class="code">
944 // runtime/JSObject.h
945
946 namespace WTF {
947
948 } // namespace WTF
949
950 using WTF::PlacementNewAdopt;
951 </pre>
952 </li>
953
954 <li id="using-in-cpp">In C++ implementation files, do not use "using" declarations
955 of any kind to import names in the standard template library.  Directly qualify
956 the names at the point they're used instead.
957
958 <h4 class="right">Right:</h4>
959 <pre class="code">
960 // HTMLBaseElement.cpp
961
962 namespace WebCore {
963
964   std::swap(a, b);
965   c = std::numeric_limits&lt;int&gt;::max()
966
967 } // namespace WebCore
968 </pre>
969 <h4 class="wrong">Wrong:</h4>
970 <pre class="code">
971 // HTMLBaseElement.cpp
972
973 using std::swap;
974
975 namespace WebCore {
976
977   swap(a, b);
978
979 } // namespace WebCore
980 </pre>
981 <h4 class="wrong">Wrong:</h4>
982 <pre class="code">
983 // HTMLBaseElement.cpp
984
985 using namespace std;
986
987 namespace WebCore {
988
989   swap(a, b);
990
991 } // namespace WebCore
992 </pre>
993 </li>
994
995 <li id="using-nested-namespaces">In implementation files, if a "using namespace" statement is
996 for a nested namespace whose parent namespace is defined in the file,
997 put the statement inside that namespace definition.
998
999 <h4 class="right">Right:</h4>
1000 <pre class="code">
1001 // HTMLBaseElement.cpp
1002
1003 namespace WebCore {
1004
1005 using namespace HTMLNames;
1006
1007 } // namespace WebCore
1008 </pre>
1009
1010 <h4 class="wrong">Wrong:</h4>
1011 <pre class="code">
1012 // HTMLBaseElement.cpp
1013
1014 using namespace WebCore::HTMLNames;
1015
1016 namespace WebCore {
1017
1018 } // namespace WebCore
1019 </pre>
1020 </li>
1021
1022 <li id="using-position">In implementation files, put all other "using" statements
1023 at the beginning of the file, before any namespace definitions and
1024 after any "include" statements.
1025
1026 <h4 class="right">Right:</h4>
1027 <pre class="code">
1028 // HTMLSelectElement.cpp
1029
1030 using namespace other;
1031
1032 namespace WebCore {
1033
1034 } // namespace WebCore
1035 </pre>
1036
1037 <h4 class="wrong">Wrong:</h4>
1038 <pre class="code">
1039 // HTMLSelectElement.cpp
1040
1041 namespace WebCore {
1042
1043 using namespace other;
1044
1045 } // namespace WebCore
1046 </pre>
1047 </li>
1048
1049 </ol>
1050
1051 <h3 id="types">Types</h3>
1052
1053 <ol>
1054 <li id="types-unsigned">
1055 Omit "int" when using "unsigned" modifier. Do not use "signed" modifier. Use "int" by itself instead.
1056 <h4 class="right">Right:</h4>
1057 <pre class="code">
1058 unsigned a;
1059 int b;
1060 </pre>
1061
1062 <h4 class="wrong">Wrong:</h4>
1063 <pre class="code">
1064 unsigned int a; // Doesn't omit "int".
1065 signed b; // Uses "signed" instead of "int".
1066 signed int c; // Doesn't omit "signed".
1067 </pre>
1068 </li>
1069 </ol>
1070
1071 <h3 id="classes">Classes</h3>
1072
1073 <ol>
1074 <li id="classes-explicit">
1075 Use a constructor to do an implicit conversion when the argument is reasonably thought of as a type conversion and the type conversion is fast. Otherwise, use the explicit keyword or a function returning the type. This only applies to single argument constructors.
1076 <h4 class="right">Right:</h4>
1077 <pre class="code">
1078 class LargeInt {
1079 public:
1080     LargeInt(int);
1081 ...
1082
1083 class Vector {
1084 public:
1085     explicit Vector(int size); // Not a type conversion.
1086     PassOwnPtr&lt;Vector&gt; create(Array); // Costly conversion.
1087 ...
1088
1089 </pre>
1090
1091 <h4 class="wrong">Wrong:</h4>
1092 <pre class="code">
1093 class Task {
1094 public:
1095     Task(ScriptExecutionContext*); // Not a type conversion.
1096     explicit Task(); // No arguments.
1097     explicit Task(ScriptExecutionContext*, Other); // More than one argument.
1098 ...
1099 </pre>
1100 </li>
1101 </ol>
1102
1103 <h3 id="comments">Comments</h3>
1104 <ol>
1105 <li id="comments-eol">Use only <i>one</i> space before end of line comments and in between sentences in comments.
1106 <h4 class="right">Right:</h4>
1107 <pre class="code">
1108 f(a, b); // This explains why the function call was done. This is another sentence.
1109 </pre>
1110
1111 <h4 class="wrong">Wrong:</h4>
1112 <pre class="code">
1113 int i;    // This is a comment with several spaces before it, which is a non-conforming style.
1114 double f; // This is another comment.  There are two spaces before this sentence which is a non-conforming style.
1115 </pre>
1116 </li>
1117
1118 <li id="comments-sentences">
1119 Make comments look like sentences by starting with a capital letter and ending with a period (punctation). One exception may be end of line comments like this "if (x == y) // false for NaN".
1120 </li>
1121
1122 <li id="comments-fixme">
1123 Use FIXME: (without attribution) to denote items that need to be addressed in the future.
1124 <h4 class="right">Right:</h4>
1125 <pre class="code">
1126 drawJpg(); // FIXME: Make this code handle jpg in addition to the png support.
1127 </pre>
1128
1129 <h4 class="wrong">Wrong:</h4>
1130 <pre class="code">
1131 drawJpg(); // FIXME(joe): Make this code handle jpg in addition to the png support.
1132 </pre>
1133 <pre class="code">
1134 drawJpg(); // TODO: Make this code handle jpg in addition to the png support.
1135 </pre>
1136 </ol>
1137 </li>
1138
1139 <script>
1140 (function() {
1141     var listItems = document.getElementsByTagName('li');
1142     var idsUsed = {};
1143     for (var i = 0; i < listItems.length; ++i) {
1144         var item = listItems[i];
1145         if (!item.id)
1146             continue;
1147         var button = document.createElement('span');
1148         button.className = 'idbutton';
1149         button.setAttribute('data-target-id', listItems[i].id);
1150         button.appendChild(document.createTextNode(' [' + listItems[i].id + ']'));
1151         button.addEventListener('click', function(event) {
1152             window.location.hash = '#' + event.currentTarget.getAttribute('data-target-id');
1153         });
1154         listItems[i].appendChild(button);
1155         if (idsUsed[item.id])
1156             alert('The id ' + item.id + ' is used more than once in this document.');
1157         idsUsed[item.id] = 1;
1158     }
1159 })();
1160 </script>
1161
1162 <?php
1163     include("../footer.inc");
1164 ?>