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