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