VirtualBox

source: vbox/trunk/doc/VBox-CodingGuidelines.cpp@ 25685

Last change on this file since 25685 was 25113, checked in by vboxsync, 15 years ago

doc: coding conventions

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 18.5 KB
Line 
1/* $Id: VBox-CodingGuidelines.cpp 25113 2009-11-30 15:55:00Z vboxsync $ */
2/** @file
3 * VBox - Coding Guidelines.
4 */
5
6/*
7 * Copyright (C) 2006-2009 Sun Microsystems, Inc.
8 *
9 * This file is part of VirtualBox Open Source Edition (OSE), as
10 * available from http://www.virtualbox.org. This file is free software;
11 * you can redistribute it and/or modify it under the terms of the GNU
12 * General Public License (GPL) as published by the Free Software
13 * Foundation, in version 2 as it comes in the "COPYING" file of the
14 * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
15 * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
16 *
17 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
18 * Clara, CA 95054 USA or visit http://www.sun.com if you need
19 * additional information or have any questions.
20 */
21
22/** @page pg_vbox_guideline VBox Coding Guidelines
23 *
24 * The VBox Coding guidelines are followed by all of VBox with the exception of
25 * the GUI and qemu. The GUI is using something close to the Qt style. Qemu is
26 * using whatever the frenchman does.
27 *
28 * There are a few compulsory rules and a bunch of optional ones. The following
29 * sections will describe these in details. In addition there is a section of
30 * Subversion 'rules'.
31 *
32 *
33 *
34 * @section sec_vbox_guideline_compulsory Compulsory
35 *
36 *
37 * - Use RT and VBOX types.
38 *
39 * - Use Runtime functions.
40 *
41 * - Use the standard bool, uintptr_t, intptr_t and [u]int[1-9+]_t types.
42 *
43 * - Avoid using plain unsigned and int.
44 *
45 * - Use static wherever possible. This makes the namespace less polluted
46 * and avoids nasty name clash problems which can occur, especially on
47 * Unix-like systems. (1)
48 *
49 * - Public names are of the form Domain[Subdomain[]]Method, using mixed
50 * casing to mark the words. The main domain is all uppercase.
51 * (Think like java, mapping domain and subdomain to packages/classes.)
52 *
53 * - Public names are always declared using the appropriate DECL macro. (2)
54 *
55 * - Internal names starts with a lowercased main domain.
56 *
57 * - Defines are all uppercase and separate words with underscore.
58 * This applies to enum values too.
59 *
60 * - Typedefs are all uppercase and contain no underscores to distinguish
61 * them from defines.
62 *
63 * - Pointer typedefs start with 'P'. If pointer to const then 'PC'.
64 *
65 * - Function typedefs start with 'FN'. If pointer to FN then 'PFN'.
66 *
67 * - All files are case sensitive.
68 *
69 * - Slashes are unix slashes ('/') runtime converts when necessary.
70 *
71 * - char strings are UTF-8.
72 *
73 * - All functions return VBox status codes. There are three general
74 * exceptions from this:
75 * -# Predicate functions. These are function which are boolean in
76 * nature and usage. They return bool. The function name will
77 * include 'Has', 'Is' or similar.
78 * -# Functions which by nature cannot possibly fail.
79 * These return void.
80 * -# "Get"-functions which return what they ask for.
81 * A get function becomes a "Query" function if there is any
82 * doubt about getting what is ask for.
83 *
84 * - VBox status codes have three subdivisions:
85 * -# Errors, which are VERR_ prefixed and negative.
86 * -# Warnings, which are VWRN_ prefixed and positive.
87 * -# Informational, which are VINF_ prefixed and positive.
88 *
89 * - Platform/OS operation are generalized and put in the IPRT.
90 *
91 * - Other useful constructs are also put in the IPRT.
92 *
93 * - The code shall not cause compiler warnings. Check this on ALL
94 * the platforms.
95 *
96 * - All files have file headers with $Id and a file tag which describes
97 * the file in a sentence or two.
98 * Note: Remember to enable keyword expansion when adding files to svn.
99 *
100 * - All public functions are fully documented in Doxygen style using the
101 * javadoc dialect (using the 'at' instead of the 'slash' as
102 * commandprefix.)
103 *
104 * - All structures in header files are described, including all their
105 * members.
106 *
107 * - All modules have a documentation 'page' in the main source file which
108 * describes the intent and actual implementation.
109 *
110 * - Code which is doing things that are not immediately comprehensible
111 * shall include explanatory comments.
112 *
113 * - Documentation and comments are kept up to date.
114 *
115 * - Headers in /include/VBox shall not contain any slash-slash C++
116 * comments, only ANSI C comments!
117 *
118 * - Comments on \#else indicates what begins while the comment on a
119 * \#endif indicates what ended.
120 *
121 *
122 * (1) It is common practice on Unix to have a single symbol namespace for an
123 * entire process. If one is careless symbols might be resolved in a
124 * different way that one expects, leading to weird problems.
125 *
126 * (2) This is common practice among most projects dealing with modules in
127 * shared libraries. The Windows / PE __declspect(import) and
128 * __declspect(export) constructs are the main reason for this.
129 * OTOH, we do perhaps have a bit too detailed graining of this in VMM...
130 *
131 *
132 * @subsection sec_vbox_guideline_compulsory_sub64 64-bit and 32-bit
133 *
134 * Here are some amendments which address 64-bit vs. 32-bit portability issues.
135 *
136 * Some facts first:
137 *
138 * - On 64-bit Windows the type long remains 32-bit. On nearly all other
139 * 64-bit platforms long is 64-bit.
140 *
141 * - On all 64-bit platforms we care about, int is 32-bit, short is 16 bit
142 * and char is 8-bit.
143 * (I don't know about any platforms yet where this isn't true.)
144 *
145 * - size_t, ssize_t, uintptr_t, ptrdiff_t and similar are all 64-bit on
146 * 64-bit platforms. (These are 32-bit on 32-bit platforms.)
147 *
148 * - There is no inline assembly support in the 64-bit Microsoft compilers.
149 *
150 *
151 * Now for the guidelines:
152 *
153 * - Never, ever, use int, long, ULONG, LONG, DWORD or similar to cast a
154 * pointer to integer. Use uintptr_t or intptr_t. If you have to use
155 * NT/Windows types, there is the choice of ULONG_PTR and DWORD_PTR.
156 *
157 * - RT_OS_WINDOWS is defined to indicate Windows. Do not use __WIN32__,
158 * __WIN64__ and __WIN__ because they are all deprecated and scheduled
159 * for removal (if not removed already). Do not use the compiler
160 * defined _WIN32, _WIN64, or similar either. The bitness can be
161 * determined by testing ARCH_BITS.
162 * Example:
163 * @code
164 * #ifdef RT_OS_WINDOWS
165 * // call win32/64 api.
166 * #endif
167 * #ifdef RT_OS_WINDOWS
168 * # if ARCH_BITS == 64
169 * // call win64 api.
170 * # else // ARCH_BITS == 32
171 * // call win32 api.
172 * # endif // ARCH_BITS == 32
173 * #else // !RT_OS_WINDOWS
174 * // call posix api
175 * #endif // !RT_OS_WINDOWS
176 * @endcode
177 *
178 * - There are RT_OS_xxx defines for each OS, just like RT_OS_WINDOWS
179 * mentioned above. Use these defines instead of any predefined
180 * compiler stuff or defines from system headers.
181 *
182 * - RT_ARCH_X86 is defined when compiling for the x86 the architecture.
183 * Do not use __x86__, __X86__, __[Ii]386__, __[Ii]586__, or similar
184 * for this purpose.
185 *
186 * - RT_ARCH_AMD64 is defined when compiling for the AMD64 architecture.
187 * Do not use __AMD64__, __amd64__ or __x64_86__.
188 *
189 * - Take care and use size_t when you have to, esp. when passing a pointer
190 * to a size_t as a parameter.
191 *
192 * - Be wary of type promotion to (signed) integer. For example the
193 * following will cause u8 to be promoted to int in the shift, and then
194 * sign extended in the assignment 64-bit:
195 * @code
196 * uint8_t u8 = 0xfe;
197 * uint64_t u64 = u8 << 24;
198 * // u64 == 0xfffffffffe000000
199 * @endcode
200 *
201 *
202 * @subsection sec_vbox_guideline_compulsory_cppmain C++ guidelines for Main
203 *
204 * Main is currently (2009) full of hard-to-maintain code that uses complicated
205 * templates. The new mid-term goal for Main is to have less custom templates
206 * instead of more for the following reasons:
207 *
208 * - Template code is harder to read and understand. Custom templates create
209 * territories which only the code writer understands.
210 *
211 * - Errors in using templates create terrible C++ compiler messages.
212 *
213 * - Template code is really hard to look at in a debugger.
214 *
215 * - Templates slow down the compiler a lot.
216 *
217 * In particular, the following bits should be considered deprecated and should
218 * NOT be used in new code:
219 *
220 * - everything in include/iprt/cpputils.h (auto_ref_ptr, exception_trap_base,
221 * char_auto_ptr and friends)
222 *
223 * Generally, in many cases, a simple class with a proper destructor can achieve
224 * the same effect as a 1,000-line template include file, and the code is
225 * much more accessible that way.
226 *
227 * Using standard STL templates like std::list, std::vector and std::map is OK.
228 * Exceptions are:
229 *
230 * - Guest Additions because we don't want to link against libstdc++ there.
231 *
232 * - std::string should not be used because we have iprt::MiniString and
233 * com::Utf8Str which can convert efficiently with COM's UTF-16 strings.
234 *
235 * - std::auto_ptr<> in general; that part of the C++ standard is just broken.
236 * Write a destructor that calls delete.
237 *
238 *
239 *
240 * @section sec_vbox_guideline_optional Optional
241 *
242 * First part is the actual coding style and all the prefixes. The second part
243 * is a bunch of good advice.
244 *
245 *
246 * @subsection sec_vbox_guideline_optional_layout The code layout
247 *
248 * - Curly brackets are not indented.
249 *
250 * - Space before the parenthesis when it comes after a C keyword.
251 *
252 * - No space between argument and parenthesis. Exception for complex
253 * expression.
254 * Example:
255 * @code
256 * if (PATMR3IsPatchGCAddr(pVM, GCPtr))
257 * @endcode
258 *
259 * - The else of an if is always the first statement on a line. (No curly
260 * stuff before it!)
261 *
262 * - else and if go on the same line if no { compound statement }
263 * follows the if.
264 * Example:
265 * @code
266 * if (fFlags & MYFLAGS_1)
267 * fFlags &= ~MYFLAGS_10;
268 * else if (fFlags & MYFLAGS_2)
269 * {
270 * fFlags &= ~MYFLAGS_MASK;
271 * fFlags |= MYFLAGS_5;
272 * }
273 * else if (fFlags & MYFLAGS_3)
274 * @endcode
275 *
276 * - The case is indented from the switch.
277 *
278 * - If a case needs curly brackets they contain the entire case, are not
279 * indented from the case, and the break or return is placed inside them.
280 * Example:
281 * @code
282 * switch (pCur->eType)
283 * {
284 * case PGMMAPPINGTYPE_PAGETABLES:
285 * {
286 * unsigned iPDE = pCur->GCPtr >> PGDIR_SHIFT;
287 * unsigned iPT = (pCur->GCPtrEnd - pCur->GCPtr) >> PGDIR_SHIFT;
288 * while (iPT-- > 0)
289 * if (pPD->a[iPDE + iPT].n.u1Present)
290 * return VERR_HYPERVISOR_CONFLICT;
291 * break;
292 * }
293 * }
294 * @endcode
295 *
296 * - In a do while construction, the while is on the same line as the
297 * closing "}" if any are used.
298 * Example:
299 * @code
300 * do
301 * {
302 * stuff;
303 * i--;
304 * } while (i > 0);
305 * @endcode
306 *
307 * - Comments are in C style. C++ style comments are used for temporary
308 * disabling a few lines of code.
309 *
310 * - Slightly complex boolean expressions are split into multiple lines,
311 * putting the operators first on the line and indenting it all according
312 * to the nesting of the expression. The purpose is to make it as easy as
313 * possible to read.
314 * Example:
315 * @code
316 * if ( RT_SUCCESS(rc)
317 * || (fFlags & SOME_FLAG))
318 * @endcode
319 *
320 * - No unnecessary parentheses in expressions (just don't over do this
321 * so that gcc / msc starts bitching). Find a correct C/C++ operator
322 * precedence table if needed.
323 *
324 *
325 * @subsection sec_vbox_guideline_optional_prefix Variable / Member Prefixes
326 *
327 * - The 'g_' (or 'g') prefix means a global variable, either on file or module level.
328 *
329 * - The 's_' (or 's') prefix means a static variable inside a function or class.
330 *
331 * - The 'm_' (or 'm') prefix means a class data member.
332 *
333 * In new code in Main, use "m_" (and common sense). As an exception, in Main,
334 * if a class encapsulates its member variables in an anonymous
335 * structure which is declared in the class, but defined only in the
336 * implementation (like this: "class X { struct Data; Data *m; }"), then
337 * the pointer to that struct is called "m" itself and its members then need no prefix,
338 * because the members are accessed with "m->member" already which is clear enough.
339 *
340 * - The 'p' prefix means pointer. For instance 'pVM' is pointer to VM.
341 *
342 * - The 'a' prefix means array. For instance 'aPages' could be read as array
343 * of pages.
344 *
345 * - The 'c' prefix means count. For instance 'cbBlock' could be read, count
346 * of bytes in block.
347 *
348 * - The 'off' prefix means offset.
349 *
350 * - The 'i' or 'idx' prefixes usually means index. Although the 'i' one can
351 * sometimes just mean signed integer.
352 *
353 * - The 'e' (or 'enm') prefix means enum.
354 *
355 * - The 'u' prefix usually means unsigned integer. Exceptions follows.
356 *
357 * - The 'u[1-9]+' prefix means a fixed bit size variable. Frequently used
358 * with the uint[1-9]+_t types and with bitfields.
359 *
360 * - The 'b' prefix means byte or bytes.
361 *
362 * - The 'f' prefix means flags. Flags are unsigned integers of some kind or bools.
363 *
364 * - The 'ch' prefix means a char, the (signed) char type.
365 *
366 * - The 'wc' prefix means a wide/windows char, the RTUTF16 type.
367 *
368 * - The 'uc' prefix means a Unicode Code point, the RTUNICP type.
369 *
370 * - The 'uch' prefix means unsigned char. It's rarely used.
371 *
372 * - The 'sz' prefix means zero terminated character string (array of chars). (UTF-8)
373 *
374 * - The 'wsz' prefix means zero terminated wide/windows character string (array of RTUTF16).
375 *
376 * - The 'usz' prefix means zero terminated Unicode string (array of RTUNICP).
377 *
378 * - The 'str' prefix means C++ string; either a std::string or, in Main, a Utf8Str.
379 *
380 * - The 'bstr' prefix, in Main, means a UTF-16 Bstr.
381 *
382 * - The 'pfn' prefix means pointer to function. Common usage is 'pfnCallback'
383 * and such like.
384 *
385 *
386 * @subsection sec_vbox_guideline_optional_misc Misc / Advice / Stuff
387 *
388 * - When writing code think as the reader.
389 *
390 * - When writing code think as the compiler.
391 *
392 * - When reading code think as if it's full of bugs - find them and fix them.
393 *
394 * - Pointer within range tests like:
395 * @code
396 * if ((uintptr_t)pv >= (uintptr_t)pvBase && (uintptr_t)pv < (uintptr_t)pvBase + cbRange)
397 * @endcode
398 * Can also be written as (assuming cbRange unsigned):
399 * @code
400 * if ((uintptr_t)pv - (uintptr_t)pvBase < cbRange)
401 * @endcode
402 * Which is shorter and potentially faster. (1)
403 *
404 * - Avoid unnecessary casting. All pointers automatically cast down to
405 * void *, at least for non class instance pointers.
406 *
407 * - It's very very bad practise to write a function larger than a
408 * screen full (1024x768) without any comprehensibility and explaining
409 * comments.
410 *
411 * - More to come....
412 *
413 *
414 * (1) Important, be very careful with the casting. In particular, note that
415 * a compiler might treat pointers as signed (IIRC).
416 *
417 *
418 *
419 *
420 * @section sec_vbox_guideline_warnings Compiler Warnings
421 *
422 * The code should when possible compile on all platforms and compilers without any
423 * warnings. That's a nice idea, however, if it means making the code harder to read,
424 * less portable, unreliable or similar, the warning should not be fixed.
425 *
426 * Some of the warnings can seem kind of innocent at first glance. So, let's take the
427 * most common ones and explain them.
428 *
429 *
430 * @subsection sec_vbox_guideline_warnings_signed_unsigned_compare Signed / Unsigned Compare
431 *
432 * GCC says: "warning: comparison between signed and unsigned integer expressions"
433 * MSC says: "warning C4018: '<|<=|==|>=|>' : signed/unsigned mismatch"
434 *
435 * The following example will not output what you expect:
436@code
437#include <stdio.h>
438int main()
439{
440 signed long a = -1;
441 unsigned long b = 2294967295;
442 if (a < b)
443 printf("%ld < %lu: true\n", a, b);
444 else
445 printf("%ld < %lu: false\n", a, b);
446 return 0;
447}
448@endcode
449 * If I understood it correctly, the compiler will convert a to an
450 * unsigned long before doing the compare.
451 *
452 *
453 *
454 * @section sec_vbox_guideline_svn Subversion Commit Rules
455 *
456 *
457 * Before checking in:
458 *
459 * - Check Tinderbox and make sure the tree is green across all platforms. If it's
460 * red on a platform, don't check in. If you want, warn in the \#vbox channel and
461 * help make the responsible person fix it.
462 * NEVER CHECK IN TO A BROKEN BUILD.
463 *
464 * - When checking in keep in mind that a commit is atomic and that the Tinderbox and
465 * developers are constantly checking out the tree. Therefore do not split up the
466 * commit unless it's into 100% independent parts. If you need to split it up in order
467 * to have sensible commit comments, make the sub-commits as rapid as possible.
468 *
469 * - If you make a user visible change, such as fixing a reported bug,
470 * make sure you add an entry to doc/manual/user_ChangeLogImpl.xml.
471 *
472 * - If you are adding files make sure set the right attributes.
473 * svn-ps.sh/cmd was created for this purpose, please make use of it.
474 *
475 *
476 * After checking in:
477 *
478 * - After checking-in, you watch Tinderbox until your check-ins clear. You do not
479 * go home. You do not sleep. You do not log out or experiment with drugs. You do
480 * not become unavailable. If you break the tree, add a comment saying that you're
481 * fixing it. If you can't fix it and need help, ask in the \#innotek channel or back
482 * out the change.
483 *
484 * (Inspired by mozilla tree rules.)
485 */
486
Note: See TracBrowser for help on using the repository browser.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette