WebKitSite/coding/coding-style.html

   1 <?php
   2         $title="WebKit Coding Style Guidelines";
   3         include("../header.inc");
   4 ?>
   5
   6
   7 <h2>WebKit Coding Style Guidelines</h2>
   8 <h3>Indenting</h3>
   9
  10 <ol>
  11 <li> Use spaces to indent. Tabs should not appear in code files (with the exception of files that require tabs, e.g. Makefiles).
  12      We have a Subversion pre-commit script that enforces this rule for most
  13      source files, preventing commits of files that don't follow this rule.
  14 </li>
  15 <li> The indent size is 4 spaces.</li>
  16 <li> Code editors should be configured to expand tabs that you type to 4 spaces.</li>
  17 </ol>
  18
  19 <h3>Braces</h3>
  20 <ol>
  21 <li> Function definitions &mdash; open and close braces should be on lines by themselves. Do not put the open brace on the same line as the function signature. For example:<br />
  22
  23 <h4 style="color: #008000 !important !important">Right:</h4>
  24 <pre style="background-color: #F2F2F2">
  25 void foo()
  26 {
  27     // do stuff
  28 }
  29 </pre>
  30
  31 <h4 style="color: #ff0000 !important">Wrong:</h4>
  32 <pre style="background-color: #F2F2F2">
  33 void foo() {
  34     // do stuff
  35 }
  36 </pre>
  37 </li>
  38 <li> Other braces, including for, while, do, switch statements and class definitions &mdash; the open brace should go on the same line as the as the control structure.<br />
  39
  40 <h4 style="color: #008000 !important">Right:</h4>
  41 <pre style="background-color: #F2F2F2">
  42 for (int i = 0; i < 10; i++) {
  43     // do stuff
  44 }
  45 </pre>
  46
  47 <h4 style="color: #ff0000 !important">Wrong:</h4>
  48 </pre>
  49 <pre style="background-color: #F2F2F2">
  50 for (int i = 0; i < 10; i++)
  51 {
  52     // do stuff
  53 }
  54 </pre>
  55 <li> If/else statements &mdash; as above, but if there is an else clause, the close brace should go on the same line as the else.
  56      Also, one-line if or else clauses should not get braces.<br />
  57 <h4 style="color: #008000 !important">Right:</h4>
  58 <pre style="background-color: #F2F2F2">
  59 if (timeToGetCoffee) {
  60     buyCoffee(&#038;coffee);
  61     chugIt(coffee);
  62 } else if (timeToGoHome)
  63     // comment on else case
  64     outtaHere = true;
  65 </pre>
  66
  67 <h4 style="color: #ff0000 !important">Wrong:</h4>
  68 <pre style="background-color: #F2F2F2">
  69 if (timeToGetCoffee)
  70 {
  71     buyCoffee(&#038;coffee);
  72     chugIt(coffee);
  73 // comment on else case
  74 } else if (timeToGoHome)
  75 {
  76     outtaHere = true;
  77 }
  78
  79 if (timeToGetCoffee) {
  80 }
  81 else
  82
  83 // comment on else case
  84
  85 if (timeToGoHome)
  86     outtaHere = true;
  87         </pre>
  88 </li>
  89 </pre>
  90 </li>
  91 </ol>
  92
  93 <h3>Parentheses</h3>
  94 <ol>
  95 <li>Function declarations and calls &mdash; do not use any spaces between the name and the open paren, inside the parentheses, or before commas that separate arguments.
  96     Do use a single space after commas that separate arguments.<br />
  97
  98 <h4 style="color: #008000 !important">Right:</h4>
  99 <pre style="background-color: #F2F2F2">
 100 int myFunction(int arg1, float arg2);
 101
 102 void noArgFunction(); // for C++ or Objective-C++
 103
 104 void noArgFunction(void); // for C or Objective-C
 105 </pre>
 106
 107 <h4 style="color: #ff0000 !important">Wrong:</h4>
 108 <pre style="background-color: #F2F2F2">
 109 int myFunction (int arg1, float arg2);
 110
 111 int myFunction( int arg1 , float arg2 );
 112
 113 void noArgFunction ();
 114 </pre>
 115 </li>
 116
 117 <li>Control structures, such as if, while, do and switch &mdash; use a single space before the open paren, but no spaces inside the parentheses.
 118
 119 </li>
 120 </ol>
 121
 122 <h3>Null, false and 0</h3>
 123 <ol>
 124 <li>In C++, the null pointer value should be written as <code>0</code>. In C it should be written as <code>NULL</code>. In Objective-C, it should be written as <code>nil</code> if it is being used as a null pointer of type <code>id</code> or another ObjC object type, otherwise <code>NULL</code>.</li>
 125 <li>True and false values of type <code>bool</code> (common in C and C++), or just generic true/false values, should be written as <code>true</code> and <code>false</code>. Values of the Objective-C <code>BOOL</code> type should be written as <code>YES</code> and <code>NO</code>.</li>
 126 <li>Tests for null pointers, false values and 0 values should all be done diretly, not through an inqueality or equality comparison.<br />
 127
 128 <h4 style="color: #008000 !important">Right:</h4>
 129 <pre style="background-color: #F2F2F2">
 130
 131 // test for true
 132 if (foo->isSomething()) {
 133     // code
 134 }
 135
 136 // test for false
 137 if (!foo->isSomething()) {
 138     // code
 139 }
 140
 141 // test for non-null
 142 if (ptr) {
 143    // code
 144 }
 145
 146 // test for null
 147 if (!ptr) {
 148    // code
 149 }
 150
 151 // test for nonzero
 152 if (count) {
 153     // code
 154 }
 155
 156 // test for zero
 157 if (!count) {
 158     // code
 159 }
 160 </pre>
 161
 162 <h4 style="color: #ff0000 !important">Wrong:</h4>
 163 <pre style="background-color: #F2F2F2">
 164 if (foo->isSomething() == true) {
 165     // code
 166 }
 167
 168 if (foo->isSomething() != false) {
 169     // code
 170 }
 171
 172 if (p == NULL) {
 173     // code
 174 }
 175
 176 if (nil != p) {
 177     // code
 178 }
 179
 180 if (count == 0) {
 181     // code
 182 }
 183 </pre>
 184 </li>
 185 </ol>
 186
 187 <h3>Names</h3>
 188 <ol>
 189 <li>General Rule: With very few exceptions, prefer embedded capitals instead of underscores for class, function and variable names.</p></li>
 190 <li>C++ and Objective-C classes, interfaces and protocols, and other type names &emdash; these names should start with a capital letter and use InterCaps.<br />
 191
 192 <h4 style="color: #008000 !important">Right:</h4>
 193 <pre style="background-color: #F2F2F2">
 194 class MyImportantClass;
 195 </pre>
 196
 197 <h4 style="color: #ff0000 !important">Wrong:</h4>
 198 <pre style="background-color: #F2F2F2">
 199 class My_important_class;
 200
 201 class myImportantClass;
 202 </pre>
 203 </li>
 204
 205 <li>Local variables should use interCaps, but the first word should start with a lowercase letter, like this:<br />
 206
 207 <h4 style="color: #008000 !important">Right:</h4>
 208 <pre style="background-color: #F2F2F2">
 209 int myInt;
 210 </pre>
 211
 212 <h4 style="color: #ff0000 !important">Wrong:</h4>
 213 <pre style="background-color: #F2F2F2">
 214 int MyInt;
 215
 216 int my_int;
 217 </pre>
 218 </li>
 219
 220 <li>Free function names in C++ should follow the same naming conventions as local variables. Most functions should be named to sound like verb phrases, like &#8220;openDoor&#8221; or &#8220;walkAroundTheBlock&#8221;. (getters, setters, predicates?)</li>
 221
 222 <li>C++ data members should be named like local variables, but with a prefix of m_.</li>
 223 <li>C++ member functions should follow the same naming convention as free functions.</li>
 224 <li>Objective-C methods should follow the usual Cocoa naming style &mdash;
 225 they should read like a phrase or sentence and each piece of the selector should start with a lowercase letter and use intercaps.</li>
 226 <li>Objective-C instance variables should be named like local variables but starting with an underscore.</li>
 227 <li>Enum members should user InterCaps with an initial capital letter.</li>
 228 <li>#defined constants should use all uppercase names with words separated by underscores.</li>
 229 <li> 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 preferrable to use an inline function in such cases instead of a macro.<br />
 230
 231 <h4 style="color: #008000 !important">Right:</h4>
 232 <pre style="background-color: #F2F2F2">
 233 #define WBStopButtonTitle() \
 234         NSLocalizedString(@\"Stop\", @\"Stop button title\")
 235 </pre>
 236
 237 <h4 style="color: #ff0000 !important">Wrong:</h4>
 238 <pre style="background-color: #F2F2F2">
 239 #define WB_STOP_BUTTON_TITLE \
 240         NSLocalizedString(@\"Stop\", @\"Stop button\")
 241
 242 #define WBStopButtontitle \
 243         NSLocalizedString(@\"Stop\", @\"Stop button\")
 244 </pre>
 245 </li>
 246
 247 <li> Acronyms in names: If an identifier includes an acronym, make the acronym all-uppercase
 248      or all-lowercase, depending on whether a word in that position would be capitalized or not.<br />
 249
 250 <h4 style="color: #008000 !important">Right:</h4>
 251 <pre style="background-color: #F2F2F2">
 252 urlVariable
 253 myURLAccessor:
 254 </pre>
 255
 256 <h4 style="color: #ff0000 !important">Wrong:</h4>
 257 <pre style="background-color: #F2F2F2">
 258 uRLVariable
 259 myUrlAccessor:
 260 </pre>
 261 </li>
 262 </ol>
 263
 264 <h3>Other Punctuation</h3>
 265
 266 <ol>
 267
 268 <li>Pointer and reference types in C++ code &mdash; Both pointer types and reference types
 269 should be written with no space between the type name and the * or &amp;.
 270
 271 <li>Pointer types in non-C++ code &mdash; Pointer types should be written with a space between the
 272 type and the * (so the * is adjacent to the following identifier if any).
 273
 274 </ol>
 275
 276 <h3>Include Statements</h3>
 277
 278 <ol>
 279
 280 <li>All files must #include "config.h" first.
 281
 282 <li>All files must #include the primary header second, just after "config.h".
 283 So for example, Node.cpp should include Node.h first, before other files.
 284 This guarantees that each header's completeness is tested, to make sure it
 285 can be compiled without requiring any other header files be included first.
 286
 287 <li>Other #include statements should be in sorted order (case sensitive, as
 288 done by the command-line sort tool or the Xcode sort selection command).
 289 Don't bother to organize them in a logical order.
 290
 291 </ol>
 292
 293 <?php
 294         include("../footer.inc");
 295 ?>