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 </ol>
 284
 285 <h3>Null, false and 0</h3>
 286 <ol>
 287 <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>
 288 <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>
 289 <li>Tests for true/false, null/non-null, and zero/non-zero should all be done without equality comparisons.<br>
 290
 291 <h4 class="right">Right:</h4>
 292 <pre class="code">
 293 if (condition)
 294     doIt();
 295
 296 if (!ptr)
 297     return;
 298
 299 if (!count)
 300     return;
 301 </pre>
 302
 303 <h4 class="wrong">Wrong:</h4>
 304 <pre class="code">
 305 if (condition == true)
 306     doIt();
 307
 308 if (ptr == NULL)
 309     return;
 310
 311 if (count == 0)
 312     return;
 313 </pre>
 314 </li>
 315 </ol>
 316
 317 <h3>Names</h3>
 318 <ol>
 319 <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.
 320 <h4 class="right">Right:</h4>
 321 <pre class="code">
 322 struct Data;
 323 size_t bufferSize;
 324 class HTMLDocument;
 325 </pre>
 326
 327 <h4 class="wrong">Wrong:</h4>
 328 <pre class="code">
 329 struct data;
 330 size_t buffer_size;
 331 class HtmlDocument;
 332 </pre>
 333 </li>
 334
 335 <li>Use full words, except in the rare case where an abbreviation would be more canonical and easier to understand.
 336 <h4 class="right">Right:</h4>
 337 <pre class="code">
 338 size_t characterSize;
 339 size_t length;
 340 short tabIndex; // more canonical
 341 </pre>
 342
 343 <h4 class="wrong">Wrong:</h4>
 344 <pre class="code">
 345 size_t charSize;
 346 size_t len;
 347 short tabulationIndex; // bizarre
 348 </pre>
 349 </li>
 350
 351 <li>Prefix C++ data members with "m_".
 352 <h4 class="right">Right:</h4>
 353 <pre class="code">
 354 class String {
 355     ...
 356     short m_length;
 357 };
 358 </pre>
 359
 360 <h4 class="wrong">Wrong:</h4>
 361 <pre class="code">
 362 class String {
 363     ...
 364     short length;
 365 };
 366 </pre>
 367 </li>
 368
 369 <li>Prefix Objective-C instance variables with "_".
 370 <h4 class="right">Right:</h4>
 371 <pre class="code">
 372 @class String
 373     ...
 374     short _length;
 375 @end
 376 </pre>
 377
 378 <h4 class="wrong">Wrong:</h4>
 379 <pre class="code">
 380 @class String
 381     ...
 382     short length;
 383 @end
 384 </pre>
 385 </li>
 386
 387 <li>Precede boolean values with words like "is" and "did".
 388 <h4 class="right">Right:</h4>
 389 <pre class="code">
 390 bool isValid;
 391 bool didSendData;
 392 </pre>
 393
 394 <h4 class="wrong">Wrong:</h4>
 395 <pre class="code">
 396 bool valid;
 397 bool sentData;
 398 </pre>
 399 </li>
 400
 401 <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.
 402 <h4 class="right">Right:</h4>
 403 <pre class="code">
 404 void setCount(size_t); // sets m_count
 405 size_t count(); // returns m_count
 406 </pre>
 407
 408 <h4 class="wrong">Wrong:</h4>
 409 <pre class="code">
 410 void setCount(size_t); // sets m_theCount
 411 size_t getCount();
 412 </pre>
 413 </li>
 414
 415 <li>Use descriptive verbs in function names.
 416 <h4 class="right">Right:</h4>
 417 <pre class="code">
 418 bool convertToASCII(short*, size_t);
 419 </pre>
 420
 421 <h4 class="wrong">Wrong:</h4>
 422 <pre class="code">
 423 bool toASCII(short*, size_t);
 424 </pre>
 425 </li>
 426
 427 <li>Leave meaningless variable names out of function declarations.
 428 <h4 class="right">Right:</h4>
 429 <pre class="code">
 430 void setCount(size_t);
 431 </pre>
 432
 433 <h4 class="wrong">Wrong:</h4>
 434 <pre class="code">
 435 void setCount(size_t count);
 436 </pre>
 437 </li>
 438
 439 <li>Objective-C method names should follow the Cocoa naming guidelines &mdash;
 440 they should read like a phrase and each piece of the selector should
 441 start with a lowercase letter and use intercaps.</li>
 442 <li>Enum members should user InterCaps with an initial capital letter.</li>
 443 <li>Prefer const to #define. Prefer inline functions to macros.</li>
 444 <li>#defined constants should use all uppercase names with words separated by underscores.</li>
 445 <li> Macros that expand to function calls or other non-constant computation: these
 446 should be named like functions, and should have parentheses at the end, even if
 447 they take no arguments (with the exception of some special macros like ASSERT).
 448 Note that usually it is preferable to use an inline function in such cases instead of a macro.<br>
 449
 450 <h4 class="right">Right:</h4>
 451 <pre class="code">
 452 #define WBStopButtonTitle() \
 453         NSLocalizedString(@"Stop", @"Stop button title")
 454 </pre>
 455
 456 <h4 class="wrong">Wrong:</h4>
 457 <pre class="code">
 458 #define WB_STOP_BUTTON_TITLE \
 459         NSLocalizedString(@"Stop", @"Stop button title")
 460
 461 #define WBStopButtontitle \
 462         NSLocalizedString(@"Stop", @"Stop button title")
 463 </pre>
 464 </li>
 465 <li>#define, #ifdef "header guards" should be named exactly the same as the file (including case), replacing the '.' with a '_'.
 466 <h4 class="right">Right:</h4>
 467 <pre class="code">
 468 // HTMLDocument.h
 469 #ifndef HTMLDocument_h
 470 #define HTMLDocument_h
 471 </pre>
 472
 473 <h4 class="wrong">Wrong:</h4>
 474 <pre class="code">
 475 // HTMLDocument.h
 476 #ifndef _HTML_DOCUMENT_H_
 477 #define _HTML_DOCUMENT_H_
 478 </pre>
 479 </li>
 480 </ol>
 481
 482 <h3>Other Punctuation</h3>
 483
 484 <ol>
 485
 486 <li>Constructors for C++ classes should initialize all of their members using C++
 487 initializer synatax.  Each member (and superclass) should be indented on a separate
 488 line, with the colon or comma preceding the member on that line.
 489
 490 <h4 class="right">Right:</h4>
 491 <pre class="code">
 492 MyClass::MyClass(Document* doc)
 493     : MySuperClass()
 494     , m_myMember(0)
 495     , m_doc(doc)
 496 {
 497 }
 498
 499 MyOtherClass::MyOtherClass()
 500     : MySuperClass()
 501 {
 502 }
 503 </pre>
 504
 505 <h4 class="wrong">Wrong:</h4>
 506 <pre class="code">
 507 MyClass::MyClass(Document* doc) : MySuperClass()
 508 {
 509     m_myMember = 0;
 510     m_doc = doc;
 511 }
 512
 513 MyOtherClass::MyOtherClass() : MySuperClass() {}
 514 </pre>
 515
 516 <li>Pointer types in non-C++ code &mdash; Pointer types should be written with a space between the
 517 type and the * (so the * is adjacent to the following identifier if any).
 518
 519 <li>Pointer and reference types in C++ code &mdash; Both pointer types and reference types
 520 should be written with no space between the type name and the * or &amp;.
 521
 522 </ol>
 523
 524 <h4 class="right">Right:</h4>
 525 <pre class="code">
 526 Image* SVGStyledElement::doSomething(PaintInfo&amp; paintInfo)
 527 {
 528   SVGStyledElement* element = static_cast&lt;SVGStyledElement*>(node());
 529   const KCDashArray&amp; dashes = dashArray();
 530 </pre>
 531
 532 <h4 class="wrong">Wrong:</h4>
 533 <pre class="code">
 534 Image *SVGStyledElement::doSomething(PaintInfo &amp;paintInfo)
 535 {
 536     SVGStyledElement *element = static_cast&lt;SVGStyledElement *>(node());
 537     const KCDashArray &amp;dashes = dashArray();
 538 </pre>
 539
 540 <h3>#include Statements</h3>
 541
 542 <ol>
 543
 544 <li>All files must #include "config.h" first.
 545
 546 <li>All files must #include the primary header second, just after "config.h".
 547 So for example, Node.cpp should include Node.h first, before other files.
 548 This guarantees that each header's completeness is tested, to make sure it
 549 can be compiled without requiring any other header files be included first.
 550
 551 <li>Other #include statements should be in sorted order (case sensitive, as
 552 done by the command-line sort tool or the Xcode sort selection command).
 553 Don't bother to organize them in a logical order.
 554
 555 </ol>
 556
 557 <?php
 558     include("../footer.inc");
 559 ?>