Some factual corrections and some updates to the coding style
[WebKit-https.git] / WebKitSite / coding / coding-style.html
index 0dc5987b94508aaa131eeac234517b4f5a6e3b99..16a1afd1dc97c218f80780f8a79bbacee39e7f94 100644 (file)
@@ -11,9 +11,7 @@
 <iframe id="sidebar" src="../sidebar.html"></iframe>
 <!--end sidebar -->
 
-<div id="banner">
-WebKit Coding Style Guidelines
-</div>
+<h1 id="banner">WebKit Coding Style Guidelines</h1>
 
 <div id="content">
 
@@ -22,7 +20,9 @@ WebKit Coding Style Guidelines
 
 <ol>
 <li> Use spaces to indent. Tabs should not appear in code files (with
-     the exception of files that require them e.g. Makefiles).
+     the exception of files that require tabs, e.g. Makefiles). We have
+     a Subversion pre-commit script that enforces this rule for most
+     source files, preventing commits of files that don't follow this rule.
 
 <li> The indent size is 4 spaces.
 
@@ -33,53 +33,43 @@ spaces.
 <h3>Braces</h3>
 
 <ol>
-<li> Function definitions - 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:
+<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:
 
 <pre>
     RIGHT:
-    
         void foo()
         {
         }
-        
-        
+
     WRONG:
-    
         void foo() {
         }
-
 </pre>
 
-<li> Loop control structures, including for, while and do statements - the open brace should go on the same line as the as the control structure. 
+<li> Loop control structures, including for, while and do statements &mdash; the open brace should go on the same line as the as the control structure. 
 
 <pre>
     RIGHT:
-    
         for (int i = 0; i < 10; i++) {
         }
                 
     WRONG:
-    
         for (int i = 0; i < 10; i++) 
         {
         }
-
 </pre>
 
-<li> If/else statements - as above, but if there is an else clause, the close brace should go on the same line as the else.
+<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.
 
 <pre>
     RIGHT:
-
         if (timeToGetCoffee) {
            buyCoffee(&coffee);
             chugIt(coffee);
         } else if (timeToGoHome)
             outtaHere = true;
 
-
     WRONG:
-
         if (timeToGetCoffee)
         {
            buyCoffee(&coffee);
@@ -93,18 +83,17 @@ spaces.
         } 
        else if (timeToGoHome) 
             outtaHere = true;
-
+</pre>
 </ol>
 
 <h3>Parentheses</h3>
 
 <ol>
 
-<li>Function declarations and calls - do not use any spaces between the name and the open paren, inside the parentheses, or before commas that separate arguments. Do use a single space after commas that separate arguments.
+<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. Do use a single space after commas that separate arguments.
 
 <pre>
     RIGHT:
-
         int myFunction(int arg1, float arg2);
         void noArgFunction();
 
@@ -114,7 +103,7 @@ spaces.
         void noArgFunction ();
 </pre>
 
-<li>Control structures, such as if, while, do and switch - use a single space before the open paren, but no spaces inside the parentheses.
+<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.
 
 </ol>
 
@@ -125,16 +114,14 @@ capitals instead of underscores for class, function and variable
 names.
 
 <li>C++ and Objective-C classes, interfaces and protocols, and other
-type names - these names should start with a capital letter and use
+type names &mdash; these names should start with a capital letter and use
 InterCaps.
 
 <pre>
     RIGHT:
-    
         class MyImportantClass
         
     WRONG:
-    
         class My_important_class
         class myImportantClass
 </pre>
@@ -144,11 +131,9 @@ start with a lowercase letter, like this:
 
 <pre>
     RIGHT:
-    
         int myInt;
         
     WRONG:
-    
         int MyInt;
         int my_int;
 </pre>
@@ -164,19 +149,13 @@ prefix of m_.
 <li>C++ member functions should follow the same naming convention as
 free functions.
 
-<li>Objective-C methods should follow the usual Cocoa naming style -
+<li>Objective-C methods should follow the usual Cocoa naming style &mdash;
 they should read like a phrase or sentence and each piece of the
 selector should start with a lowercase letter and use intercaps.
 
 <li>Objective-C instance variables should be named like local
 variables but starting with an underscore.
 
-<li>Pointer and reference types - pointer types should be written with
-a space between the type name and the * (so the * is adjacent to the
-following identifier if any). For reference types, the &amp; goes next to
-the type name.
-
-
 <li>Enum members should user InterCaps with an initial capital letter.
 
 <li>#defined constants should use all uppercase names with words
@@ -202,14 +181,40 @@ separated by underscores.
 
 <pre>
     RIGHT:
-
         urlVariable
         myURLAccessor:
 
     WRONG:
-
         uRLVariable
         myUrlAccessor:
 </pre>
 </ol>
 
+<h3>Other Punctuation</h3>
+
+<ol>
+
+<li>Pointer and reference types in C++ code &mdash; Both pointer types and reference types
+should be written with no space between the type name and the * or &amp;.
+
+<li>Pointer types in non-C++ code &mdash; Pointer types should be written with a space between the
+type and the * (so the * is adjacent to the following identifier if any).
+
+</ol>
+
+<h3>Include Statements</h3>
+
+<ol>
+
+<li>All files must #include "config.h" first.
+
+<li>All 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, to make sure it
+can be compiled without requiring any other header files be included first.
+
+<li>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.
+
+</ol>