Web Inspector: provide a way to enable/disable event listeners
[WebKit-https.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 [](#spacing-function-paren) In Objective-C, do not place spaces between the start of a block and its arguments, or the start of a block and its opening brace. **Do** place a space between argument lists and the opening brace of the block.
238
239 ###### Right:
240
241 ```cpp
242 block = ^{
243 ...
244 };
245
246 block = ^(int, int) {
247 ...
248 };
249
250 ```
251
252 ###### Wrong:
253
254 ```cpp
255 block = ^ {
256 ...
257 };
258
259 block = ^ (int, int){
260 ...
261 };
262
263 ```
264
265 ### Line breaking
266
267 [](#linebreaking-multiple-statements) Each statement should get its own line.
268
269 ###### Right:
270
271 ```cpp
272 x++;
273 y++;
274 if (condition)
275     doIt();
276 ```
277
278 ###### Wrong:
279
280 ```cpp
281 x++; y++;
282 if (condition) doIt();
283 ```
284
285 [](#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.
286
287 ###### Right:
288
289 ```cpp
290 if (condition) {
291     ...
292 } else {
293     ...
294 }
295
296 if (condition)
297     doSomething();
298 else
299     doSomethingElse();
300
301 if (condition)
302     doSomething();
303 else {
304     ...
305 }
306 ```
307
308 ###### Wrong:
309
310 ```cpp
311 if (condition) {
312     ...
313 }
314 else {
315     ...
316 }
317
318 if (condition) doSomething(); else doSomethingElse();
319
320 if (condition) doSomething(); else {
321     ...
322 }
323 ```
324
325 [](#linebreaking-else-if) An `else if` statement should be written as an `if` statement when the prior `if` concludes with a `return` statement.
326
327 ###### Right:
328
329 ```cpp
330 if (condition) {
331     ...
332     return someValue;
333 }
334 if (condition) {
335     ...
336 }
337 ```
338
339 ###### Wrong:
340
341 ```cpp
342 if (condition) {
343     ...
344     return someValue;
345 } else if (condition) {
346     ...
347 }
348 ```
349
350 ### Braces
351
352 [](#braces-function) Function definitions: place each brace on its own line.
353
354 ###### Right:
355
356 ```cpp
357 int main()
358 {
359     ...
360 }
361 ```
362
363 ###### Wrong:
364
365 ```cpp
366 int main() {
367     ...
368 }
369 ```
370
371 [](#braces-blocks) Other braces: place the open brace on the line preceding the code block; place the close brace on its own line.
372
373 ###### Right:
374
375 ```cpp
376 class MyClass {
377     ...
378 };
379
380 namespace WebCore {
381     ...
382 }
383
384 for (int i = 0; i < 10; ++i) {
385     ...
386 }
387 ```
388
389 ###### Wrong:
390
391 ```cpp
392 class MyClass 
393 {
394     ...
395 };
396 ```
397
398 [](#braces-one-line) One-line control clauses should not use braces unless comments are included or a single statement spans multiple lines.
399
400 ###### Right:
401
402 ```cpp
403 if (condition)
404     doIt();
405
406 if (condition) {
407     // Some comment
408     doIt();
409 }
410
411 if (condition) {
412     myFunction(reallyLongParam1, reallyLongParam2, ...
413         reallyLongParam5);
414 }
415 ```
416
417 ###### Wrong:
418
419 ```cpp
420 if (condition) {
421     doIt();
422 }
423
424 if (condition)
425     // Some comment
426     doIt();
427
428 if (condition)
429     myFunction(reallyLongParam1, reallyLongParam2, ...
430         reallyLongParam5);
431 ```
432
433 [](#braces-empty-block) Control clauses without a body should use empty braces:
434
435 ###### Right:
436
437 ```cpp
438 for ( ; current; current = current->next) { }
439 ```
440
441 ###### Wrong:
442
443 ```cpp
444 for ( ; current; current = current->next);
445 ```
446
447 ### Null, false and zero
448
449 [](#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.
450
451 [](#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`.
452
453 [](#zero-comparison) Tests for true/false, null/non-null, and zero/non-zero should all be done without equality comparisons.
454
455 ###### Right:
456
457 ```cpp
458 if (condition)
459     doIt();
460
461 if (!ptr)
462     return;
463
464 if (!count)
465     return;
466 ```
467
468 ###### Wrong:
469
470 ```cpp
471 if (condition == true)
472     doIt();
473
474 if (ptr == NULL)
475     return;
476
477 if (count == 0)
478     return;
479 ```
480
481 [](#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.
482
483 ### Floating point literals
484
485 [](#float-suffixes) Unless required in order to force floating point math, do not append `.0`, `.f` and `.0f` to floating point literals.
486
487 ###### Right:
488
489 ```cpp
490 const double duration = 60;
491
492 void setDiameter(float diameter)
493 {
494     radius = diameter / 2;
495 }
496
497 setDiameter(10);
498
499 const int framesPerSecond = 12;
500 double frameDuration = 1.0 / framesPerSecond;
501 ```
502
503 ###### Wrong:
504
505 ```cpp
506 const double duration = 60.0;
507
508 void setDiameter(float diameter)
509 {
510     radius = diameter / 2.f;
511 }
512
513 setDiameter(10.f);
514
515 const int framesPerSecond = 12;
516 double frameDuration = 1 / framesPerSecond; // integer division
517 ```
518
519 ### Names
520
521 [](#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.
522
523 ###### Right:
524
525 ```cpp
526 struct Data;
527 size_t bufferSize;
528 class HTMLDocument;
529 String mimeType();
530 ```
531
532 ###### Wrong:
533
534 ```cpp
535 struct data;
536 size_t buffer_size;
537 class HtmlDocument;
538 String MIMEType();
539 ```
540
541 [](#names-full-words) Use full words, except in the rare case where an abbreviation would be more canonical and easier to understand.
542
543 ###### Right:
544
545 ```cpp
546 size_t characterSize;
547 size_t length;
548 short tabIndex; // more canonical
549 ```
550
551 ###### Wrong:
552
553 ```cpp
554 size_t charSize;
555 size_t len;
556 short tabulationIndex; // bizarre
557 ```
558
559 [](#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_".
560
561 ###### Right:
562
563 ```cpp
564 class String {
565 public:
566     ...
567
568 private:
569     short m_length;
570 };
571 ```
572
573 ###### Wrong:
574
575 ```cpp
576 class String {
577 public:
578     ...
579
580     short length;
581 };
582 ```
583
584 [](#names-objc-instance-variables) Prefix Objective-C instance variables with "_".
585
586 ###### Right:
587
588 ```cpp
589 @class String
590     ...
591     short _length;
592 @end
593 ```
594
595 ###### Wrong:
596
597 ```cpp
598 @class String
599     ...
600     short length;
601 @end
602 ```
603
604 [](#names-bool) Precede boolean values with words like "is" and "did".
605
606 ###### Right:
607
608 ```cpp
609 bool isValid;
610 bool didSendData;
611 ```
612
613 ###### Wrong:
614
615 ```cpp
616 bool valid;
617 bool sentData;
618 ```
619
620 [](#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.
621
622 ###### Right:
623
624 ```cpp
625 void setCount(size_t); // sets m_count
626 size_t count(); // returns m_count
627 ```
628
629 ###### Wrong:
630
631 ```cpp
632 void setCount(size_t); // sets m_theCount
633 size_t getCount();
634 ```
635
636 [](#names-out-argument) Precede getters that return values through out arguments with the word "get".
637
638 ###### Right:
639
640 ```cpp
641 void getInlineBoxAndOffset(InlineBox*&, int& caretOffset) const;
642 ```
643
644 ###### Wrong:
645
646 ```cpp
647 void inlineBoxAndOffset(InlineBox*&, int& caretOffset) const;
648 ```
649
650 [](#names-verb) Use descriptive verbs in function names.
651
652 ###### Right:
653
654 ```cpp
655 bool convertToASCII(short*, size_t);
656 ```
657
658 ###### Wrong:
659
660 ```cpp
661 bool toASCII(short*, size_t);
662 ```
663
664 [](#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.
665
666 ###### Right:
667
668 ```cpp
669 void setCount(size_t);
670
671 void doSomething(ScriptExecutionContext*);
672 ```
673
674 ###### Wrong:
675
676 ```cpp
677 void setCount(size_t count);
678
679 void doSomething(ScriptExecutionContext* context);
680 ```
681
682 [](#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.
683
684 ###### Right:
685
686 ```cpp
687 doSomething(something, AllowFooBar);
688 paintTextWithShadows(context, ..., textStrokeWidth > 0, isHorizontal());
689 setResizable(false);
690 ```
691
692 ###### Wrong:
693
694 ```cpp
695 doSomething(something, false);
696 setResizable(NotResizable);
697 ```
698
699 [](#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.
700
701 [](#names-enum-members) Enum members should use InterCaps with an initial capital letter.
702
703 [](#names-const-to-define) Prefer `const` to `#define`. Prefer inline functions to macros.
704
705 [](#names-define-constants) `#defined` constants should use all uppercase names with words separated by underscores.
706
707 [](#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.
708
709 ###### Right:
710
711 ```cpp
712 #define WBStopButtonTitle() \
713         NSLocalizedString(@"Stop", @"Stop button title")
714 ```
715
716 ###### Wrong:
717
718 ```cpp
719 #define WB_STOP_BUTTON_TITLE \
720         NSLocalizedString(@"Stop", @"Stop button title")
721
722 #define WBStopButtontitle \
723         NSLocalizedString(@"Stop", @"Stop button title")
724 ```
725
726 [](#header-guards) Use `#pragma once` instead of `#define` and `#ifdef` for header guards.
727
728 ###### Right:
729
730 ```cpp
731 // HTMLDocument.h
732 #pragma once
733 ```
734
735 ###### Wrong:
736
737 ```cpp
738 // HTMLDocument.h
739 #ifndef HTMLDocument_h
740 #define HTMLDocument_h
741 ```
742
743 [](#names-protectors-this) Ref and RefPtr objects meant to protect `this` from deletion should be named "protectedThis".
744
745 ###### Right:
746
747 ```cpp
748 RefPtr<Node> protectedThis(this);
749 Ref<Element> protectedThis(*this);
750 RefPtr<Widget> protectedThis = this;
751 ```
752
753 ###### Wrong:
754
755 ```cpp
756 RefPtr<Node> protector(this);
757 Ref<Node> protector = *this;
758 RefPtr<Widget> self(this);
759 Ref<Element> elementRef(*this);
760 ```
761
762 [](#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.
763
764 ###### Right:
765
766 ```cpp
767 RefPtr<Element> protector(&element);
768 RefPtr<Element> protector = &element;
769 RefPtr<Node> protectedNode(node);
770 RefPtr<Widget> protectedMainWidget(m_mainWidget);
771 RefPtr<Loader> protectedFontLoader = m_fontLoader;
772 ```
773
774 ###### Wrong:
775
776 ```cpp
777 RefPtr<Node> nodeRef(&rootNode);
778 Ref<Element> protect(*element);
779 RefPtr<Node> protectorNode(node);
780 RefPtr<Widget> protected = widget;
781 ```
782
783 ### Other Punctuation
784
785 [](#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.
786
787 ###### Right:
788
789 ```cpp
790 MyClass::MyClass(Document* document)
791     : MySuperClass()
792     , m_myMember(0)
793     , m_document(document)
794 {
795 }
796
797 MyOtherClass::MyOtherClass()
798     : MySuperClass()
799 {
800 }
801 ```
802
803 ###### Wrong:
804
805 ```cpp
806 MyClass::MyClass(Document* document) : MySuperClass()
807 {
808     m_myMember = 0;
809     m_document = document;
810 }
811
812 MyOtherClass::MyOtherClass() : MySuperClass() {}
813 ```
814
815 [](#punctuation-vector-index) Prefer index over iterator in Vector iterations for terse, easier-to-read code.
816
817 ###### Right:
818
819 ```cpp
820 for (auto& frameView : frameViews)
821     frameView->updateLayoutAndStyleIfNeededRecursive();
822 ```
823
824
825 #### OK:
826
827 ```cpp
828 unsigned frameViewsCount = frameViews.size();
829 for (unsigned i = 0; i < frameViewsCount; ++i)
830     frameViews[i]->updateLayoutAndStyleIfNeededRecursive();
831 ```
832
833 ###### Wrong:
834
835 ```cpp
836 const Vector<RefPtr<FrameView> >::iterator end = frameViews.end();
837 for (Vector<RefPtr<FrameView> >::iterator it = frameViews.begin(); it != end; ++it)
838     (*it)->updateLayoutAndStyleIfNeededRecursive();
839 ```
840
841 ### Pointers and References
842
843 [](#pointers-non-cpp) **Pointer types in non-C++ code**
844 Pointer types should be written with a space between the type and the `*` (so the `*` is adjacent to the following identifier if any).
845
846 [](#pointers-cpp) **Pointer and reference types in C++ code**
847 Both pointer types and reference types should be written with no space between the type name and the `*` or `&`.
848
849 ###### Right:
850
851 ```cpp
852 Image* SVGStyledElement::doSomething(PaintInfo& paintInfo)
853 {
854     SVGStyledElement* element = static_cast<SVGStyledElement*>(node());
855     const KCDashArray& dashes = dashArray();
856 ```
857
858 ###### Wrong:
859
860 ```cpp
861 Image *SVGStyledElement::doSomething(PaintInfo &paintInfo)
862 {
863     SVGStyledElement *element = static_cast<SVGStyledElement *>(node());
864     const KCDashArray &dashes = dashArray();
865 ```
866
867 [](#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.
868
869 ###### Right:
870
871 ```cpp
872 void MyClass::getSomeValue(OutArgumentType& outArgument) const
873 {
874     outArgument = m_value;
875 }
876
877 void MyClass::doSomething(OutArgumentType* outArgument) const
878 {
879     doSomething();
880     if (outArgument)
881         *outArgument = m_value;
882 }
883 ```
884
885 ###### Wrong:
886
887 ```cpp
888 void MyClass::getSomeValue(OutArgumentType* outArgument) const
889 {
890     *outArgument = m_value;
891 }
892 ```
893
894 ### #include Statements
895
896 [](#include-config-h) All implementation files must `#include` `config.h` first. Header files should never include `config.h`.
897
898 ###### Right:
899
900 ```cpp
901 // RenderLayer.h
902 #include "Node.h"
903 #include "RenderObject.h"
904 #include "RenderView.h"
905 ```
906
907 ###### Wrong:
908
909 ```cpp
910 // RenderLayer.h
911 #include "config.h"
912
913 #include "RenderObject.h"
914 #include "RenderView.h"
915 #include "Node.h"
916 ```
917
918 [](#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.
919
920 [](#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.
921
922 ###### Right:
923
924 ```cpp
925 // HTMLDivElement.cpp
926 #include "config.h"
927 #include "HTMLDivElement.h"
928
929 #include "Attribute.h"
930 #include "HTMLElement.h"
931 #include "QualifiedName.h"
932 ```
933
934 ###### Wrong:
935
936 ```cpp
937 // HTMLDivElement.cpp
938 #include "HTMLElement.h"
939 #include "HTMLDivElement.h"
940 #include "QualifiedName.h"
941 #include "Attribute.h"
942 ```
943
944 [](#include-system) Includes of system headers must come after includes of other headers.
945
946 ###### Right:
947
948 ```cpp
949 // ConnectionQt.cpp
950 #include "ArgumentEncoder.h"
951 #include "ProcessLauncher.h"
952 #include "WebPageProxyMessageKinds.h"
953 #include "WorkItem.h"
954 #include <QApplication>
955 #include <QLocalServer>
956 #include <QLocalSocket>
957 ```
958
959 ###### Wrong:
960
961 ```cpp
962 // ConnectionQt.cpp
963 #include "ArgumentEncoder.h"
964 #include "ProcessLauncher.h"
965 #include <QApplication>
966 #include <QLocalServer>
967 #include <QLocalSocket>
968 #include "WebPageProxyMessageKinds.h"
969 #include "WorkItem.h"
970 ```
971
972 ### "using" Statements
973
974 [](#using-in-headers) In header files, do not use "using" statements in namespace (or global) scope.
975
976 ###### Right:
977
978 ```cpp
979 // wtf/Vector.h
980
981 namespace WTF {
982
983 class VectorBuffer {
984     using std::min;
985     ...
986 };
987
988 } // namespace WTF
989 ```
990
991 ###### Wrong:
992
993 ```cpp
994 // wtf/Vector.h
995
996 namespace WTF {
997
998 using std::min;
999
1000 class VectorBuffer {
1001     ...
1002 };
1003
1004 } // namespace WTF
1005 ```
1006
1007 [](#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.
1008
1009 ###### Right:
1010
1011 ```cpp
1012 // wtf/Vector.h
1013
1014 namespace WTF {
1015
1016 } // namespace WTF
1017
1018 using WTF::Vector;
1019 ```
1020
1021 ###### Wrong:
1022
1023 ```cpp
1024 // wtf/Vector.h
1025
1026 namespace WTF {
1027
1028 } // namespace WTF
1029
1030 using namespace WTF;
1031 ```
1032
1033 ###### Wrong:
1034
1035 ```cpp
1036 // runtime/JSObject.h
1037
1038 namespace WTF {
1039
1040 } // namespace WTF
1041
1042 using WTF::PlacementNewAdopt;
1043 ```
1044
1045 [](#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.
1046
1047 ###### Right:
1048
1049 ```cpp
1050 // HTMLBaseElement.cpp
1051
1052 namespace WebCore {
1053
1054   std::swap(a, b);
1055   c = std::numeric_limits<int>::max()
1056
1057 } // namespace WebCore
1058 ```
1059
1060 ###### Wrong:
1061
1062 ```cpp
1063 // HTMLBaseElement.cpp
1064
1065 using std::swap;
1066
1067 namespace WebCore {
1068
1069   swap(a, b);
1070
1071 } // namespace WebCore
1072 ```
1073
1074 ###### Wrong:
1075
1076 ```cpp
1077 // HTMLBaseElement.cpp
1078
1079 using namespace std;
1080
1081 namespace WebCore {
1082
1083   swap(a, b);
1084
1085 } // namespace WebCore
1086 ```
1087
1088 [](#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.
1089
1090 ###### Right:
1091
1092 ```cpp
1093 // HTMLBaseElement.cpp
1094
1095 namespace WebCore {
1096
1097 using namespace HTMLNames;
1098
1099 } // namespace WebCore
1100 ```
1101
1102 ###### Wrong:
1103
1104 ```cpp
1105 // HTMLBaseElement.cpp
1106
1107 using namespace WebCore::HTMLNames;
1108
1109 namespace WebCore {
1110
1111 } // namespace WebCore
1112 ```
1113
1114 [](#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.
1115
1116 ###### Right:
1117
1118 ```cpp
1119 // HTMLSelectElement.cpp
1120
1121 using namespace other;
1122
1123 namespace WebCore {
1124
1125 } // namespace WebCore
1126 ```
1127
1128 ###### Wrong:
1129
1130 ```cpp
1131 // HTMLSelectElement.cpp
1132
1133 namespace WebCore {
1134
1135 using namespace other;
1136
1137 } // namespace WebCore
1138 ```
1139
1140 ### Types
1141
1142 [](#types-unsigned) Omit "int" when using "unsigned" modifier. Do not use "signed" modifier. Use "int" by itself instead.
1143
1144 ###### Right:
1145
1146 ```cpp
1147 unsigned a;
1148 int b;
1149 ```
1150
1151 ###### Wrong:
1152
1153 ```cpp
1154 unsigned int a; // Doesn't omit "int".
1155 signed b; // Uses "signed" instead of "int".
1156 signed int c; // Doesn't omit "signed".
1157 ```
1158
1159 ### Classes
1160
1161 [](#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.
1162
1163 ###### Right:
1164
1165 ```cpp
1166 class LargeInt {
1167 public:
1168     LargeInt(int);
1169 ...
1170
1171 class Vector {
1172 public:
1173     explicit Vector(int size); // Not a type conversion.
1174     Vector create(Array); // Costly conversion.
1175 ...
1176
1177 ```
1178
1179 ###### Wrong:
1180
1181 ```cpp
1182 class Task {
1183 public:
1184     Task(ScriptExecutionContext&); // Not a type conversion.
1185     explicit Task(); // No arguments.
1186     explicit Task(ScriptExecutionContext&, Other); // More than one argument.
1187 ...
1188 ```
1189
1190 ### Singleton pattern
1191
1192 [](#singleton-static-member) Use a static member function named "singleton()" to access the instance of the singleton.
1193
1194 ###### Right:
1195
1196 ```cpp
1197 class MySingleton {
1198 public:
1199     static MySingleton& singleton();
1200 ...
1201 ```
1202
1203 ###### Wrong:
1204
1205 ```cpp
1206 class MySingleton {
1207 public:
1208     static MySingleton& shared();
1209 ...
1210 ```
1211
1212 ###### Wrong:
1213
1214 ```cpp
1215 class MySingleton {
1216 ...
1217 };
1218
1219 MySingleton& mySingleton(); // free function.
1220 ```
1221
1222 ### Comments
1223
1224 [](#comments-eol) Use only _one_ space before end of line comments and in between sentences in comments.
1225
1226 ###### Right:
1227
1228 ```cpp
1229 f(a, b); // This explains why the function call was done. This is another sentence.
1230 ```
1231
1232 ###### Wrong:
1233
1234 ```cpp
1235 int i;    // This is a comment with several spaces before it, which is a non-conforming style.
1236 double f; // This is another comment.  There are two spaces before this sentence which is a non-conforming style.
1237 ```
1238
1239 [](#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`.
1240
1241 [](#comments-fixme) Use FIXME: (without attribution) to denote items that need to be addressed in the future.
1242
1243 ###### Right:
1244
1245 ```cpp
1246 drawJpg(); // FIXME: Make this code handle jpg in addition to the png support.
1247 ```
1248
1249 ###### Wrong:
1250
1251 ```cpp
1252 drawJpg(); // FIXME(joe): Make this code handle jpg in addition to the png support.
1253 ```
1254
1255 ```cpp
1256 drawJpg(); // TODO: Make this code handle jpg in addition to the png support.
1257 ```
1258
1259 ### Overriding Virtual Methods
1260
1261 [](#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.
1262
1263 ###### Right:
1264
1265 ```cpp
1266 class Person {
1267 public:
1268     virtual String description() { ... };
1269 }
1270
1271 class Student : public Person {
1272 public:
1273     String description() override { ... }; // This is correct because it only contains the "override" keyword to indicate that the method is overridden.
1274 }
1275
1276 ```
1277
1278 ```cpp
1279 class Person {
1280 public:
1281     virtual String description() { ... };
1282 }
1283
1284 class Student : public Person {
1285 public:
1286     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".
1287 }
1288
1289 ```
1290
1291 ###### Wrong:
1292
1293 ```cpp
1294 class Person {
1295 public:
1296     virtual String description() { ... };
1297 }
1298
1299 class Student : public Person {
1300 public:
1301     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.
1302 }
1303 ```
1304
1305 ```cpp
1306 class Person {
1307 public:
1308     virtual String description() { ... };
1309 }
1310
1311 class Student : public Person {
1312 public:
1313     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.
1314 }
1315 ```
1316
1317 ```cpp
1318 class Person {
1319 public:
1320     virtual String description() { ... };
1321 }
1322
1323 class Student : public Person {
1324 public:
1325     virtual String description() { ... }; // This is incorrect because it uses the "virtual" keyword to indicate that the method is overridden.
1326 }
1327 ```