Reviewed by Tim H.
[WebKit-https.git] / 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 them e.g. Makefiles).</li>
12 <li> The indent size is 4 spaces.</li>
13 <li> Code editors should be configured to expand tabs that you type to 4 spaces.</li>
14 </ol>
15
16 <h3>Braces</h3>
17 <ol>
18 <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:<br />
19
20 <h4 style="color: #008000 !important !important">Right:</h4>
21 <pre style="background-color: #F2F2F2">
22 void foo()
23 {
24     // do stuff
25 }
26 </pre>
27
28 <h4 style="color: #ff0000 !important">Wrong:</h4>
29 <pre style="background-color: #F2F2F2">
30 void foo() {
31     // do stuff
32 }
33 </pre>
34 </li>
35 <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.<br />
36
37 <h4 style="color: #008000 !important">Right:</h4>
38 <pre style="background-color: #F2F2F2">
39 for (int i = 0; i < 10; i++) {
40     // do stuff
41 }
42 </pre>
43
44 <h4 style="color: #ff0000 !important">Wrong:</h4>
45 </pre>
46 <pre style="background-color: #F2F2F2">
47 for (int i = 0; i < 10; i++)
48 {
49     // do stuff
50 }
51 </pre>
52 <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. Also, one-line  if or else clauses should not get braces.<br />
53
54 <h4 style="color: #008000 !important">Right:</h4>
55 <pre style="background-color: #F2F2F2">
56 if (timeToGetCoffee) {
57     buyCoffee(&#038;coffee);
58     chugIt(coffee);
59 } else if (timeToGoHome)
60     // comment on else case
61     outtaHere = true;
62 </pre>
63
64 <h4 style="color: #ff0000 !important">Wrong:</h4>
65 <pre style="background-color: #F2F2F2">
66 if (timeToGetCoffee)
67 {
68     buyCoffee(&#038;coffee);
69     chugIt(coffee);
70 // comment on else case
71 } else if (timeToGoHome)
72 {
73     outtaHere = true;
74 }
75         
76 if (timeToGetCoffee) {
77 }
78 else
79         
80 // comment on else case
81         
82 if (timeToGoHome)
83     outtaHere = true;
84         </pre>
85 </li>
86 </pre>
87 </li>
88 </ol>
89
90 <h3>Parentheses</h3>
91 <ol>
92 <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.<br />
93
94 <h4 style="color: #008000 !important">Right:</h4>
95 <pre style="background-color: #F2F2F2">
96 int myFunction(int arg1, float arg2);
97         
98 void noArgFunction(); // for C++ or Objective-C++
99         
100 void noArgFunction(void); // for C or Objective-C
101 </pre>
102
103 <h4 style="color: #ff0000 !important">Wrong:</h4>
104 <pre style="background-color: #F2F2F2">
105 int myFunction (int arg1, float arg2);
106         
107 int myFunction( int arg1 , float arg2 );
108         
109 void noArgFunction ();
110 </pre>
111 </li>
112
113 <li>Control structures, such as if, while, do and switch - use a single space before the open paren, but no spaces inside the parentheses.
114
115 </li>
116 </ol>
117
118 <h3>Null, false and 0</h3>
119 <ol>
120 <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>
121 <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>
122 <li>Tests for null pointers, false values and 0 values should all be done diretly, not through an inqueality or equality comparison.<br />
123
124 <h4 style="color: #008000 !important">Right:</h4>
125 <pre style="background-color: #F2F2F2">
126         
127 // test for true
128 if (foo->isSomething()) {
129     // code
130 }
131         
132 // test for false
133 if (!foo->isSomething()) {
134     // code
135 }
136         
137 // test for non-null
138 if (ptr) {
139    // code
140 }
141         
142 // test for null
143 if (!ptr) {
144    // code
145 }
146         
147 // test for nonzero
148 if (count) {
149     // code
150 }
151         
152 // test for zero
153 if (!count) {
154     // code
155 }
156 </pre>
157
158 <h4 style="color: #ff0000 !important">Wrong:</h4>
159 <pre style="background-color: #F2F2F2">
160 if (foo->isSomething() == true) {
161     // code
162 }
163         
164 if (foo->isSomething() != false) {
165     // code
166 }
167         
168 if (p == NULL) {
169     // code
170 }
171         
172 if (nil != p) {
173     // code
174 }
175         
176 if (count == 0) {
177     // code
178 }
179 </pre>
180 </li>
181 </ol>
182
183 <h3>Names</h3>
184 <ol>
185 <li>General Rule: With very few exceptions, prefer embedded capitals instead of underscores for class, function and variable names.</p></li>
186 <li>C++ and Objective-C classes, interfaces and protocols, and other type names - these names should start with a capital letter and use InterCaps.<br />
187
188 <h4 style="color: #008000 !important">Right:</h4>
189 <pre style="background-color: #F2F2F2">
190 class MyImportantClass;
191 </pre>
192
193 <h4 style="color: #ff0000 !important">Wrong:</h4>
194 <pre style="background-color: #F2F2F2">
195 class My_important_class;
196         
197 class myImportantClass;
198 </pre>
199 </li>
200
201 <li>Local variables should use interCaps, but the first word should start with a lowercase letter, like this:<br />
202
203 <h4 style="color: #008000 !important">Right:</h4>
204 <pre style="background-color: #F2F2F2">
205 int myInt;
206 </pre>
207
208 <h4 style="color: #ff0000 !important">Wrong:</h4>
209 <pre style="background-color: #F2F2F2">
210 int MyInt;
211         
212 int my_int;
213 </pre>
214 </li>
215
216 <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>
217
218 <li>C++ data members should be named like local variables, but with a prefix of m_.</li>
219 <li>C++ member functions should follow the same naming convention as free functions.</li>
220 <li>Objective-C methods should follow the usual Cocoa naming style - they should read like a phrase or sentence and each piece of the selector should start with a lowercase letter and use intercaps.</li>
221 <li>Objective-C instance variables should be named like local variables but starting with an underscore.</li>
222 <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>
223 <li>Enum members should user InterCaps with an initial capital letter.</li>
224 <li>#defined constants should use all uppercase names with words separated by underscores.</li>
225 <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 />
226
227 <h4 style="color: #008000 !important">Right:</h4>
228 <pre style="background-color: #F2F2F2">
229 #define WBStopButtonTitle() \
230         NSLocalizedString(@\"Stop\", @\"Stop button title\")
231 </pre>
232
233 <h4 style="color: #ff0000 !important">Wrong:</h4>
234 <pre style="background-color: #F2F2F2">
235 #define WB_STOP_BUTTON_TITLE \
236         NSLocalizedString(@\"Stop\", @\"Stop button\")
237
238 #define WBStopButtontitle \
239         NSLocalizedString(@\"Stop\", @\"Stop button\")
240 </pre>
241 </li>
242
243 <li> Acronyms in names: If an identifier includes an acronym, make the acronym all-uppercase or all-lowercase, depending on whether a word in that position would be capitalized or not.<br />
244
245 <h4 style="color: #008000 !important">Right:</h4>
246 <pre style="background-color: #F2F2F2">
247 urlVariable
248 myURLAccessor:
249 </pre>
250
251 <h4 style="color: #ff0000 !important">Wrong:</h4>
252 <pre style="background-color: #F2F2F2">
253 uRLVariable
254 myUrlAccessor:
255 </pre>
256 </li>
257 </ol>
258 <?php
259         include("../footer.inc");
260 ?>