Reviewed by Maciej.
[WebKit-https.git] / 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: #008000;
13 }
14
15 .wrong {
16   color: #ff0000;
17 }
18 </style>
19
20
21 <h2>WebKit Coding Style Guidelines</h2>
22 <h3>Indenting</h3>
23
24 <ol>
25 <li> Use spaces to indent. Tabs should not appear in code files (with the exception of files that require tabs, e.g. Makefiles).
26      We have a Subversion pre-commit script that enforces this rule for most
27      source files, preventing commits of files that don't follow this rule.
28 </li>
29 <li> The indent size is 4 spaces.</li>
30 <li> Code editors should be configured to expand tabs that you type to 4 spaces.</li>
31 </ol>
32
33 <h3>Braces</h3>
34 <ol>
35 <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>
36
37 <h4 class="right">Right:</h4>
38 <pre class="code">
39 void foo()
40 {
41     // do stuff
42 }
43 </pre>
44
45 <h4 class="wrong">Wrong:</h4>
46 <pre class="code">
47 void foo() {
48     // do stuff
49 }
50 </pre>
51 </li>
52 <li> Other braces, including for, while, do, switch statements and class definitions &mdash; the open brace should go on the same line as the control structure.<br>
53
54 <h4 class="right">Right:</h4>
55 <pre class="code">
56 for (int i = 0; i &lt; 10; i++) {
57     // do stuff
58 }
59 </pre>
60
61 <h4 class="wrong">Wrong:</h4>
62 <pre class="code">
63 for (int i = 0; i &lt; 10; i++)
64 {
65     // do stuff
66 }
67 </pre>
68 <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.
69      Also, one-line if or else clauses should not get braces.<br>
70 <h4 class="right">Right:</h4>
71 <pre class="code">
72 if (timeToGetCoffee) {
73     buyCoffee(&#038;coffee);
74     chugIt(coffee);
75 } else if (timeToGoHome)
76     // comment on else case
77     outtaHere = true;
78 </pre>
79
80 <h4 class="wrong">Wrong:</h4>
81 <pre class="code">
82 if (timeToGetCoffee)
83 {
84     buyCoffee(&#038;coffee);
85     chugIt(coffee);
86 // comment on else case
87 } else if (timeToGoHome)
88 {
89     outtaHere = true;
90 }
91     
92 if (timeToGetCoffee) {
93 }
94 else
95     
96 // comment on else case
97     
98 if (timeToGoHome)
99     outtaHere = true;
100 </pre>
101 </li>
102 </ol>
103
104 <h3>Parentheses</h3>
105 <ol>
106 <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.
107     Do use a single space after commas that separate arguments.<br>
108
109 <h4 class="right">Right:</h4>
110 <pre class="code">
111 int myFunction(int arg1, float arg2);
112
113 void noArgFunction(); // for C++ or Objective-C++
114
115 void noArgFunction(void); // for C or Objective-C
116 </pre>
117
118 <h4 class="wrong">Wrong:</h4>
119 <pre class="code">
120 int myFunction (int arg1, float arg2);
121
122 int myFunction( int arg1 , float arg2 );
123
124 void noArgFunction ();
125 </pre>
126 </li>
127
128 <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.
129
130 </li>
131 </ol>
132
133 <h3>Null, false and 0</h3>
134 <ol>
135 <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>
136 <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>
137 <li>Tests for null pointers, false values and 0 values should all be done directly, not through an inequality or equality comparison.<br>
138
139 <h4 class="right">Right:</h4>
140 <pre class="code">
141     
142 // test for true
143 if (foo->isSomething()) {
144     // code
145 }
146     
147 // test for false
148 if (!foo->isSomething()) {
149     // code
150 }
151     
152 // test for non-null
153 if (ptr) {
154    // code
155 }
156     
157 // test for null
158 if (!ptr) {
159    // code
160 }
161     
162 // test for nonzero
163 if (count) {
164     // code
165 }
166     
167 // test for zero
168 if (!count) {
169     // code
170 }
171 </pre>
172
173 <h4 class="wrong">Wrong:</h4>
174 <pre class="code">
175 if (foo->isSomething() == true) {
176     // code
177 }
178     
179 if (foo->isSomething() != false) {
180     // code
181 }
182     
183 if (p == NULL) {
184     // code
185 }
186     
187 if (nil != p) {
188     // code
189 }
190     
191 if (count == 0) {
192     // code
193 }
194 </pre>
195 </li>
196 </ol>
197
198 <h3>Names</h3>
199 <ol>
200 <li>General Rule: With very few exceptions, prefer embedded capitals instead of underscores for class, function and variable names.</li>
201 <li>C++ and Objective-C classes, interfaces and protocols, and other type names &mdash; these names should start with a capital letter and use InterCaps.<br>
202
203 <h4 class="right">Right:</h4>
204 <pre class="code">
205 class MyImportantClass;
206 </pre>
207
208 <h4 class="wrong">Wrong:</h4>
209 <pre class="code">
210 class My_important_class;
211     
212 class myImportantClass;
213 </pre>
214 </li>
215
216 <li>Local variables should use interCaps, but the first word should start with a lowercase letter, like this:<br>
217
218 <h4 class="right">Right:</h4>
219 <pre class="code">
220 int myInt;
221 </pre>
222
223 <h4 class="wrong">Wrong:</h4>
224 <pre class="code">
225 int MyInt;
226     
227 int my_int;
228 </pre>
229 </li>
230
231 <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>
232
233 <li>C++ data members should be named like local variables, but with a prefix of m_.</li>
234 <li>C++ member functions should follow the same naming convention as free functions.</li>
235 <li>Objective-C methods should follow the usual Cocoa naming style &mdash;
236 they should read like a phrase or sentence and each piece of the selector should start with a lowercase letter and use intercaps.</li>
237 <li>Objective-C instance variables should be named like local variables but starting with an underscore.</li>
238 <li>Enum members should user InterCaps with an initial capital letter.</li>
239 <li>#defined constants should use all uppercase names with words separated by underscores.</li>
240 <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>
241
242 <h4 class="right">Right:</h4>
243 <pre class="code">
244 #define WBStopButtonTitle() \
245         NSLocalizedString(@"Stop", @"Stop button title")
246 </pre>
247
248 <h4 class="wrong">Wrong:</h4>
249 <pre class="code">
250 #define WB_STOP_BUTTON_TITLE \
251         NSLocalizedString(@"Stop", @"Stop button title")
252
253 #define WBStopButtontitle \
254         NSLocalizedString(@"Stop", @"Stop button title")
255 </pre>
256 </li>
257
258 <li> Acronyms in names: If an identifier includes an acronym, make the acronym all-uppercase
259      or all-lowercase, depending on whether a word in that position would be capitalized or not.<br>
260
261 <h4 class="right">Right:</h4>
262 <pre class="code">
263 urlVariable
264 myURLAccessor:
265 </pre>
266
267 <h4 class="wrong">Wrong:</h4>
268 <pre class="code">
269 uRLVariable
270 myUrlAccessor:
271 </pre>
272 </li>
273 </ol>
274
275 <h3>Other Punctuation</h3>
276
277 <ol>
278
279 <li>Constructors for C++ classes should initialize all of their members using C++ constructor synatax.  Each member (and superclass) should be indented on a separate line, with the colon or comma preceding the member on that line.
280
281 <h4 class="right">Right:</h4>
282 <pre class="code">
283 MyClass::MyClass(Document* doc)
284     : MySuperClass()
285     , m_myMember(0)
286     , m_doc(doc)
287 {
288 }
289
290 MyOtherClass::MyOtherClass()
291     : MySuperClass()
292 {
293 }
294 </pre>
295
296 <h4 class="wrong">Wrong:</h4>
297 <pre class="code">
298 MyClass::MyClass(Document* doc) : MySuperClass()
299 {
300     m_myMember = 0;
301     m_doc = doc;
302 }
303
304 MyOtherClass::MyOtherClass() : MySuperClass() {}
305 </pre>
306
307 <li>Pointer types in non-C++ code &mdash; Pointer types should be written with a space between the
308 type and the * (so the * is adjacent to the following identifier if any).
309
310 <li>Pointer and reference types in C++ code &mdash; Both pointer types and reference types
311 should be written with no space between the type name and the * or &amp;.
312
313 </ol>
314
315 <h4 class="right">Right:</h4>
316 <pre class="code">
317 Image* SVGStyledElement::doSomething(PaintInfo&amp; paintInfo)
318 {
319   SVGStyledElement* element = static_cast&lt;SVGStyledElement*>(node());
320   const KCDashArray&amp; dashes = dashArray();
321 </pre>
322
323 <h4 class="wrong">Wrong:</h4>
324 <pre class="code">
325 Image *SVGStyledElement::doSomething(PaintInfo &amp;paintInfo)
326 {
327     SVGStyledElement *element = static_cast&lt;SVGStyledElement *>(node());
328     const KCDashArray &amp;dashes = dashArray();
329 </pre>
330
331 <h3>Include Statements</h3>
332
333 <ol>
334
335 <li>All files must #include "config.h" first.
336
337 <li>All files must #include the primary header second, just after "config.h".
338 So for example, Node.cpp should include Node.h first, before other files.
339 This guarantees that each header's completeness is tested, to make sure it
340 can be compiled without requiring any other header files be included first.
341
342 <li>Other #include statements should be in sorted order (case sensitive, as
343 done by the command-line sort tool or the Xcode sort selection command).
344 Don't bother to organize them in a logical order.
345
346 </ol>
347
348 <?php
349     include("../footer.inc");
350 ?>