WebKitSite/coding/coding-style.html

   1 <?php
   2     $title="WebKit Coding Style Guidelines";
   3     include("../header.inc");
   4 ?>
   5
   6 <style type="text/css">
   7 pre .code {
   8    background-color: #F2F2F2;
   9 }
  10
  11 .right {
  12   color: #080 !important;
  13 }
  14
  15 .wrong {
  16   color: #f00 !important;
  17 }
  18 </style>
  19
  20
  21 <h2>WebKit Coding Style Guidelines</h2>
  22 <h3>Indentation</h3>
  23
  24 <ol>
  25 <li> Use spaces, not tabs. Tabs should only appear in files that require them for semantic meaning, like Makefiles.
  26 </li>
  27 <li> The indent size is 4 spaces.
  28 <h4 class="right">Right:</h4>
  29 <pre class="code">
  30 int main()
  31 {
  32     return 0;
  33 }
  34 </pre>
  35
  36 <h4 class="wrong">Wrong:</h4>
  37 <pre class="code">
  38 int main()
  39 {
  40         return 0;
  41 }
  42 </pre>
  43 </li>
  44 <li>In a header, code inside a namespace should be indented.
  45 <h4 class="right">Right:</h4>
  46 <pre class="code">
  47 // Document.h
  48 namespace WebCore {
  49
  50     class Document {
  51         Document();
  52         ...
  53     };
  54
  55 } // namespace WebCore
  56 </pre>
  57
  58 <h4 class="wrong">Wrong:</h4>
  59 <pre class="code">
  60 // Document.h
  61 namespace WebCore {
  62
  63 class Document {
  64     Document();
  65     ...
  66 };
  67
  68 } // namespace WebCore
  69 </pre>
  70 </li>
  71
  72 <li>In an implementation file, code inside a namespace should <em>not</em> be indented.
  73 <h4 class="right">Right:</h4>
  74 <pre class="code">
  75 // Document.cpp
  76 namespace WebCore {
  77
  78 Document::Document()
  79 {
  80     ...
  81 }
  82
  83 } // namespace WebCore
  84 </pre>
  85
  86 <h4 class="wrong">Wrong:</h4>
  87 <pre class="code">
  88 // Document.cpp
  89 namespace WebCore {
  90
  91     Document::Document()
  92     {
  93         ...
  94     }
  95
  96 } // namespace WebCore
  97 </pre>
  98 </li>
  99 <li>A case label should line up with its switch statement.  The case statement is indented.
 100 <h4 class="right">Right:</h4>
 101 <pre class="code">
 102 switch (condition) {
 103 case fooCondition:
 104 case barCondition:
 105     i++;
 106     break;
 107 default:
 108     i--;
 109 }
 110 </pre>
 111
 112 <h4 class="wrong">Wrong:</h4>
 113 <pre class="code">
 114 switch (condition) {
 115     case fooCondition:
 116     case barCondition:
 117         i++;
 118         break;
 119     default:
 120         i--;
 121 }
 122 </pre>
 123 </li>
 124 </ol>
 125
 126 <h3>Spacing</h3>
 127 <ol>
 128 <li>Do not place spaces around unary operators.
 129 <h4 class="right">Right:</h4>
 130 <pre class="code">
 131 i++;
 132 </pre>
 133
 134 <h4 class="wrong">Wrong:</h4>
 135 <pre class="code">
 136 i ++;
 137 </pre>
 138 </li>
 139
 140 <li><em>Do</em> place spaces around binary and ternary operators.
 141 <h4 class="right">Right:</h4>
 142 <pre class="code">
 143 y = m * x + b;
 144 f(a, b);
 145 c = a | b;
 146 return condition ? 1 : 0;
 147 </pre>
 148
 149 <h4 class="wrong">Wrong:</h4>
 150 <pre class="code">
 151 y=m*x+b;
 152 f(a,b);
 153 c = a|b;
 154 return condition ? 1:0;
 155 </pre>
 156 </li>
 157
 158 <li>Place spaces between control statements and their parentheses.
 159 <h4 class="right">Right:</h4>
 160 <pre class="code">
 161 if (condition)
 162     doIt();
 163 </pre>
 164
 165 <h4 class="wrong">Wrong:</h4>
 166 <pre class="code">
 167 if(condition)
 168     doIt();
 169 </pre>
 170 </li>
 171
 172 <li>Do not place spaces between a function and its parentheses, or between a parenthesis and its content.
 173 <h4 class="right">Right:</h4>
 174 <pre class="code">
 175 f(a, b);
 176 </pre>
 177
 178 <h4 class="wrong">Wrong:</h4>
 179 <pre class="code">
 180 f (a, b);
 181 f( a, b );
 182 </pre>
 183 </li>
 184 </ol>
 185
 186 <h3>Line breaking</h3>
 187 <ol>
 188 <li>Each statement should get its own line.
 189 <h4 class="right">Right:</h4>
 190 <pre class="code">
 191 x++;
 192 y++;
 193 if (condition)
 194     doIt();
 195 </pre>
 196
 197 <h4 class="wrong">Wrong:</h4>
 198 <pre class="code">
 199 x++; y++;
 200 if (condition) doIt();
 201 </pre>
 202 </li>
 203
 204 <li>An else statement should go on the same line as a preceding close brace.
 205 <h4 class="right">Right:</h4>
 206 <pre class="code">
 207 if (condition) {
 208     ...
 209 } else {
 210     ...
 211 }
 212 </pre>
 213
 214 <h4 class="wrong">Wrong:</h4>
 215 <pre class="code">
 216 if (condition) {
 217     ...
 218 }
 219 else {
 220     ...
 221 }
 222 </pre>
 223 </li>
 224 </ol>
 225
 226 <h3>Braces</h3>
 227 <ol>
 228 <li> Function definitions: place each brace on its own line.
 229
 230 <h4 class="right">Right:</h4>
 231 <pre class="code">
 232 int main()
 233 {
 234     ...
 235 }
 236 </pre>
 237
 238 <h4 class="wrong">Wrong:</h4>
 239 <pre class="code">
 240 int main() {
 241     ...
 242 }
 243 </pre>
 244 </li>
 245 <li> Other braces: place the open brace on the line preceding the code block; place the close brace on its own line.
 246
 247 <h4 class="right">Right:</h4>
 248 <pre class="code">
 249 class MyClass {
 250     ...
 251 };
 252
 253 namespace WebCore {
 254     ...
 255 }
 256
 257 for (int i = 0; i &lt; 10; i++) {
 258     ...
 259 }
 260 </pre>
 261
 262 <h4 class="wrong">Wrong:</h4>
 263 <pre class="code">
 264 class MyClass
 265 {
 266     ...
 267 };
 268 </pre>
 269 <li>One-line control clauses should not use braces
 270 <h4 class="right">Right:</h4>
 271 <pre class="code">
 272 if (condition)
 273     doIt();
 274 </pre>
 275
 276 <h4 class="wrong">Wrong:</h4>
 277 <pre class="code">
 278 if (condition) {
 279     doIt();
 280 }
 281 </pre>
 282 </li>
 283
 284 <li>Control clauses without a body should use empty braces:
 285 <h4 class="right">Right:</h4>
 286 <pre class="code">
 287 for ( ; current; current = current->next) { }
 288 </pre>
 289
 290 <h4 class="wrong">Wrong:</h4>
 291 <pre class="code">
 292 for ( ; current; current = current->next);
 293 </pre>
 294 </li>
 295 </ol>
 296
 297 <h3>Null, false and 0</h3>
 298 <ol>
 299 <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 and Objective-C++, follow the guideline for C or C++, respectively, but use <code>nil</code> to represent a null Objective-C object.</li>
 300 <li>C++ and C <code>bool</code> values should be written as <code>true</code> and <code>false</code>. Objective-C <code>BOOL</code> values should be written as <code>YES</code> and <code>NO</code>.</li>
 301 <li>Tests for true/false, null/non-null, and zero/non-zero should all be done without equality comparisons.<br>
 302
 303 <h4 class="right">Right:</h4>
 304 <pre class="code">
 305 if (condition)
 306     doIt();
 307
 308 if (!ptr)
 309     return;
 310
 311 if (!count)
 312     return;
 313 </pre>
 314
 315 <h4 class="wrong">Wrong:</h4>
 316 <pre class="code">
 317 if (condition == true)
 318     doIt();
 319
 320 if (ptr == NULL)
 321     return;
 322
 323 if (count == 0)
 324     return;
 325 </pre>
 326 </li>
 327 </ol>
 328
 329 <h3>Names</h3>
 330 <ol>
 331 <li>Use CamelCase. Capitalize the first letter of a class, struct, protocol, or namespace name. Lower-case the first letter of a variable or function name. Fully capitalize acronyms.
 332 <h4 class="right">Right:</h4>
 333 <pre class="code">
 334 struct Data;
 335 size_t bufferSize;
 336 class HTMLDocument;
 337 </pre>
 338
 339 <h4 class="wrong">Wrong:</h4>
 340 <pre class="code">
 341 struct data;
 342 size_t buffer_size;
 343 class HtmlDocument;
 344 </pre>
 345 </li>
 346
 347 <li>Use full words, except in the rare case where an abbreviation would be more canonical and easier to understand.
 348 <h4 class="right">Right:</h4>
 349 <pre class="code">
 350 size_t characterSize;
 351 size_t length;
 352 short tabIndex; // more canonical
 353 </pre>
 354
 355 <h4 class="wrong">Wrong:</h4>
 356 <pre class="code">
 357 size_t charSize;
 358 size_t len;
 359 short tabulationIndex; // bizarre
 360 </pre>
 361 </li>
 362
 363 <li>Prefix C++ data members with "m_".
 364 <h4 class="right">Right:</h4>
 365 <pre class="code">
 366 class String {
 367     ...
 368     short m_length;
 369 };
 370 </pre>
 371
 372 <h4 class="wrong">Wrong:</h4>
 373 <pre class="code">
 374 class String {
 375     ...
 376     short length;
 377 };
 378 </pre>
 379 </li>
 380
 381 <li>Prefix Objective-C instance variables with "_".
 382 <h4 class="right">Right:</h4>
 383 <pre class="code">
 384 @class String
 385     ...
 386     short _length;
 387 @end
 388 </pre>
 389
 390 <h4 class="wrong">Wrong:</h4>
 391 <pre class="code">
 392 @class String
 393     ...
 394     short length;
 395 @end
 396 </pre>
 397 </li>
 398
 399 <li>Precede boolean values with words like "is" and "did".
 400 <h4 class="right">Right:</h4>
 401 <pre class="code">
 402 bool isValid;
 403 bool didSendData;
 404 </pre>
 405
 406 <h4 class="wrong">Wrong:</h4>
 407 <pre class="code">
 408 bool valid;
 409 bool sentData;
 410 </pre>
 411 </li>
 412
 413 <li>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.
 414 <h4 class="right">Right:</h4>
 415 <pre class="code">
 416 void setCount(size_t); // sets m_count
 417 size_t count(); // returns m_count
 418 </pre>
 419
 420 <h4 class="wrong">Wrong:</h4>
 421 <pre class="code">
 422 void setCount(size_t); // sets m_theCount
 423 size_t getCount();
 424 </pre>
 425 </li>
 426
 427 <li>Use descriptive verbs in function names.
 428 <h4 class="right">Right:</h4>
 429 <pre class="code">
 430 bool convertToASCII(short*, size_t);
 431 </pre>
 432
 433 <h4 class="wrong">Wrong:</h4>
 434 <pre class="code">
 435 bool toASCII(short*, size_t);
 436 </pre>
 437 </li>
 438
 439 <li>Leave meaningless variable names out of function declarations.
 440 <h4 class="right">Right:</h4>
 441 <pre class="code">
 442 void setCount(size_t);
 443 </pre>
 444
 445 <h4 class="wrong">Wrong:</h4>
 446 <pre class="code">
 447 void setCount(size_t count);
 448 </pre>
 449 </li>
 450
 451 <li>Objective-C method names should follow the Cocoa naming guidelines &mdash;
 452 they should read like a phrase and each piece of the selector should
 453 start with a lowercase letter and use intercaps.</li>
 454 <li>Enum members should user InterCaps with an initial capital letter.</li>
 455 <li>Prefer const to #define. Prefer inline functions to macros.</li>
 456 <li>#defined constants should use all uppercase names with words separated by underscores.</li>
 457 <li> Macros that expand to function calls or other non-constant computation: these
 458 should be named like functions, and should have parentheses at the end, even if
 459 they take no arguments (with the exception of some special macros like ASSERT).
 460 Note that usually it is preferable to use an inline function in such cases instead of a macro.<br>
 461
 462 <h4 class="right">Right:</h4>
 463 <pre class="code">
 464 #define WBStopButtonTitle() \
 465         NSLocalizedString(@"Stop", @"Stop button title")
 466 </pre>
 467
 468 <h4 class="wrong">Wrong:</h4>
 469 <pre class="code">
 470 #define WB_STOP_BUTTON_TITLE \
 471         NSLocalizedString(@"Stop", @"Stop button title")
 472
 473 #define WBStopButtontitle \
 474         NSLocalizedString(@"Stop", @"Stop button title")
 475 </pre>
 476 </li>
 477 <li>#define, #ifdef "header guards" should be named exactly the same as the file (including case), replacing the '.' with a '_'.
 478 <h4 class="right">Right:</h4>
 479 <pre class="code">
 480 // HTMLDocument.h
 481 #ifndef HTMLDocument_h
 482 #define HTMLDocument_h
 483 </pre>
 484
 485 <h4 class="wrong">Wrong:</h4>
 486 <pre class="code">
 487 // HTMLDocument.h
 488 #ifndef _HTML_DOCUMENT_H_
 489 #define _HTML_DOCUMENT_H_
 490 </pre>
 491 </li>
 492 </ol>
 493
 494 <h3>Other Punctuation</h3>
 495
 496 <ol>
 497
 498 <li>Constructors for C++ classes should initialize all of their members using C++
 499 initializer syntax.  Each member (and superclass) should be indented on a separate
 500 line, with the colon or comma preceding the member on that line.
 501
 502 <h4 class="right">Right:</h4>
 503 <pre class="code">
 504 MyClass::MyClass(Document* doc)
 505     : MySuperClass()
 506     , m_myMember(0)
 507     , m_doc(doc)
 508 {
 509 }
 510
 511 MyOtherClass::MyOtherClass()
 512     : MySuperClass()
 513 {
 514 }
 515 </pre>
 516
 517 <h4 class="wrong">Wrong:</h4>
 518 <pre class="code">
 519 MyClass::MyClass(Document* doc) : MySuperClass()
 520 {
 521     m_myMember = 0;
 522     m_doc = doc;
 523 }
 524
 525 MyOtherClass::MyOtherClass() : MySuperClass() {}
 526 </pre>
 527
 528 <li>Pointer types in non-C++ code &mdash; Pointer types should be written with a space between the
 529 type and the * (so the * is adjacent to the following identifier if any).
 530
 531 <li>Pointer and reference types in C++ code &mdash; Both pointer types and reference types
 532 should be written with no space between the type name and the * or &amp;.
 533
 534 <h4 class="right">Right:</h4>
 535 <pre class="code">
 536 Image* SVGStyledElement::doSomething(PaintInfo&amp; paintInfo)
 537 {
 538   SVGStyledElement* element = static_cast&lt;SVGStyledElement*>(node());
 539   const KCDashArray&amp; dashes = dashArray();
 540 </pre>
 541
 542 <h4 class="wrong">Wrong:</h4>
 543 <pre class="code">
 544 Image *SVGStyledElement::doSomething(PaintInfo &amp;paintInfo)
 545 {
 546     SVGStyledElement *element = static_cast&lt;SVGStyledElement *>(node());
 547     const KCDashArray &amp;dashes = dashArray();
 548 </pre>
 549
 550 </ol>
 551
 552 <h3>#include Statements</h3>
 553
 554 <ol>
 555
 556 <li>All files must #include "config.h" first.
 557
 558 <li>All files must #include the primary header second, just after "config.h".
 559 So for example, Node.cpp should include Node.h first, before other files.
 560 This guarantees that each header's completeness is tested, to make sure it
 561 can be compiled without requiring any other header files be included first.
 562
 563 <li>Other #include statements should be in sorted order (case sensitive, as
 564 done by the command-line sort tool or the Xcode sort selection command).
 565 Don't bother to organize them in a logical order.
 566
 567 </ol>
 568
 569 <?php
 570     include("../footer.inc");
 571 ?>