[19010] | 1 | /* $Id: VBox-CodingGuidelines.cpp 53944 2015-01-23 03:01:42Z vboxsync $ */
|
---|
[6303] | 2 | /** @file
|
---|
| 3 | * VBox - Coding Guidelines.
|
---|
| 4 | */
|
---|
| 5 |
|
---|
| 6 | /*
|
---|
[44528] | 7 | * Copyright (C) 2006-2012 Oracle Corporation
|
---|
[6303] | 8 | *
|
---|
[8155] | 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.
|
---|
[6303] | 16 | */
|
---|
| 17 |
|
---|
| 18 | /** @page pg_vbox_guideline VBox Coding Guidelines
|
---|
| 19 | *
|
---|
| 20 | * The VBox Coding guidelines are followed by all of VBox with the exception of
|
---|
[26352] | 21 | * qemu. Qemu is using whatever the frenchman does.
|
---|
[6303] | 22 | *
|
---|
| 23 | * There are a few compulsory rules and a bunch of optional ones. The following
|
---|
| 24 | * sections will describe these in details. In addition there is a section of
|
---|
| 25 | * Subversion 'rules'.
|
---|
| 26 | *
|
---|
| 27 | *
|
---|
| 28 | *
|
---|
| 29 | * @section sec_vbox_guideline_compulsory Compulsory
|
---|
| 30 | *
|
---|
| 31 | *
|
---|
[30954] | 32 | * - The indentation size is 4 chars.
|
---|
| 33 | *
|
---|
| 34 | * - Tabs are only ever used in makefiles.
|
---|
| 35 | *
|
---|
[6303] | 36 | * - Use RT and VBOX types.
|
---|
| 37 | *
|
---|
| 38 | * - Use Runtime functions.
|
---|
| 39 | *
|
---|
| 40 | * - Use the standard bool, uintptr_t, intptr_t and [u]int[1-9+]_t types.
|
---|
| 41 | *
|
---|
| 42 | * - Avoid using plain unsigned and int.
|
---|
| 43 | *
|
---|
| 44 | * - Use static wherever possible. This makes the namespace less polluted
|
---|
[16197] | 45 | * and avoids nasty name clash problems which can occur, especially on
|
---|
| 46 | * Unix-like systems. (1)
|
---|
[6303] | 47 | *
|
---|
[16197] | 48 | * - Public names are of the form Domain[Subdomain[]]Method, using mixed
|
---|
[6303] | 49 | * casing to mark the words. The main domain is all uppercase.
|
---|
| 50 | * (Think like java, mapping domain and subdomain to packages/classes.)
|
---|
| 51 | *
|
---|
| 52 | * - Public names are always declared using the appropriate DECL macro. (2)
|
---|
| 53 | *
|
---|
| 54 | * - Internal names starts with a lowercased main domain.
|
---|
| 55 | *
|
---|
| 56 | * - Defines are all uppercase and separate words with underscore.
|
---|
| 57 | * This applies to enum values too.
|
---|
| 58 | *
|
---|
| 59 | * - Typedefs are all uppercase and contain no underscores to distinguish
|
---|
| 60 | * them from defines.
|
---|
| 61 | *
|
---|
[16169] | 62 | * - Pointer typedefs start with 'P'. If pointer to const then 'PC'.
|
---|
[6303] | 63 | *
|
---|
[16169] | 64 | * - Function typedefs start with 'FN'. If pointer to FN then 'PFN'.
|
---|
[6303] | 65 | *
|
---|
| 66 | * - All files are case sensitive.
|
---|
| 67 | *
|
---|
| 68 | * - Slashes are unix slashes ('/') runtime converts when necessary.
|
---|
| 69 | *
|
---|
| 70 | * - char strings are UTF-8.
|
---|
| 71 | *
|
---|
[16169] | 72 | * - All functions return VBox status codes. There are three general
|
---|
| 73 | * exceptions from this:
|
---|
| 74 | * -# Predicate functions. These are function which are boolean in
|
---|
| 75 | * nature and usage. They return bool. The function name will
|
---|
| 76 | * include 'Has', 'Is' or similar.
|
---|
[6303] | 77 | * -# Functions which by nature cannot possibly fail.
|
---|
| 78 | * These return void.
|
---|
| 79 | * -# "Get"-functions which return what they ask for.
|
---|
| 80 | * A get function becomes a "Query" function if there is any
|
---|
| 81 | * doubt about getting what is ask for.
|
---|
| 82 | *
|
---|
| 83 | * - VBox status codes have three subdivisions:
|
---|
| 84 | * -# Errors, which are VERR_ prefixed and negative.
|
---|
| 85 | * -# Warnings, which are VWRN_ prefixed and positive.
|
---|
| 86 | * -# Informational, which are VINF_ prefixed and positive.
|
---|
| 87 | *
|
---|
| 88 | * - Platform/OS operation are generalized and put in the IPRT.
|
---|
| 89 | *
|
---|
| 90 | * - Other useful constructs are also put in the IPRT.
|
---|
| 91 | *
|
---|
[16169] | 92 | * - The code shall not cause compiler warnings. Check this on ALL
|
---|
[6303] | 93 | * the platforms.
|
---|
| 94 | *
|
---|
| 95 | * - All files have file headers with $Id and a file tag which describes
|
---|
| 96 | * the file in a sentence or two.
|
---|
| 97 | * Note: Remember to enable keyword expansion when adding files to svn.
|
---|
| 98 | *
|
---|
| 99 | * - All public functions are fully documented in Doxygen style using the
|
---|
[16169] | 100 | * javadoc dialect (using the 'at' instead of the 'slash' as
|
---|
| 101 | * commandprefix.)
|
---|
[6303] | 102 | *
|
---|
[16169] | 103 | * - All structures in header files are described, including all their
|
---|
[6303] | 104 | * members.
|
---|
| 105 | *
|
---|
| 106 | * - All modules have a documentation 'page' in the main source file which
|
---|
| 107 | * describes the intent and actual implementation.
|
---|
| 108 | *
|
---|
[16169] | 109 | * - Code which is doing things that are not immediately comprehensible
|
---|
| 110 | * shall include explanatory comments.
|
---|
[6303] | 111 | *
|
---|
| 112 | * - Documentation and comments are kept up to date.
|
---|
| 113 | *
|
---|
[16169] | 114 | * - Headers in /include/VBox shall not contain any slash-slash C++
|
---|
| 115 | * comments, only ANSI C comments!
|
---|
[6303] | 116 | *
|
---|
[21449] | 117 | * - Comments on \#else indicates what begins while the comment on a
|
---|
| 118 | * \#endif indicates what ended.
|
---|
[6303] | 119 | *
|
---|
[21449] | 120 | *
|
---|
[6303] | 121 | * (1) It is common practice on Unix to have a single symbol namespace for an
|
---|
| 122 | * entire process. If one is careless symbols might be resolved in a
|
---|
| 123 | * different way that one expects, leading to weird problems.
|
---|
| 124 | *
|
---|
| 125 | * (2) This is common practice among most projects dealing with modules in
|
---|
| 126 | * shared libraries. The Windows / PE __declspect(import) and
|
---|
| 127 | * __declspect(export) constructs are the main reason for this.
|
---|
[16169] | 128 | * OTOH, we do perhaps have a bit too detailed graining of this in VMM...
|
---|
[6303] | 129 | *
|
---|
| 130 | *
|
---|
| 131 | * @subsection sec_vbox_guideline_compulsory_sub64 64-bit and 32-bit
|
---|
| 132 | *
|
---|
| 133 | * Here are some amendments which address 64-bit vs. 32-bit portability issues.
|
---|
| 134 | *
|
---|
| 135 | * Some facts first:
|
---|
| 136 | *
|
---|
| 137 | * - On 64-bit Windows the type long remains 32-bit. On nearly all other
|
---|
| 138 | * 64-bit platforms long is 64-bit.
|
---|
| 139 | *
|
---|
| 140 | * - On all 64-bit platforms we care about, int is 32-bit, short is 16 bit
|
---|
| 141 | * and char is 8-bit.
|
---|
| 142 | * (I don't know about any platforms yet where this isn't true.)
|
---|
| 143 | *
|
---|
| 144 | * - size_t, ssize_t, uintptr_t, ptrdiff_t and similar are all 64-bit on
|
---|
| 145 | * 64-bit platforms. (These are 32-bit on 32-bit platforms.)
|
---|
| 146 | *
|
---|
| 147 | * - There is no inline assembly support in the 64-bit Microsoft compilers.
|
---|
| 148 | *
|
---|
| 149 | *
|
---|
| 150 | * Now for the guidelines:
|
---|
| 151 | *
|
---|
| 152 | * - Never, ever, use int, long, ULONG, LONG, DWORD or similar to cast a
|
---|
| 153 | * pointer to integer. Use uintptr_t or intptr_t. If you have to use
|
---|
| 154 | * NT/Windows types, there is the choice of ULONG_PTR and DWORD_PTR.
|
---|
| 155 | *
|
---|
| 156 | * - RT_OS_WINDOWS is defined to indicate Windows. Do not use __WIN32__,
|
---|
[16169] | 157 | * __WIN64__ and __WIN__ because they are all deprecated and scheduled
|
---|
[6303] | 158 | * for removal (if not removed already). Do not use the compiler
|
---|
| 159 | * defined _WIN32, _WIN64, or similar either. The bitness can be
|
---|
| 160 | * determined by testing ARCH_BITS.
|
---|
| 161 | * Example:
|
---|
| 162 | * @code
|
---|
| 163 | * #ifdef RT_OS_WINDOWS
|
---|
| 164 | * // call win32/64 api.
|
---|
| 165 | * #endif
|
---|
| 166 | * #ifdef RT_OS_WINDOWS
|
---|
| 167 | * # if ARCH_BITS == 64
|
---|
| 168 | * // call win64 api.
|
---|
| 169 | * # else // ARCH_BITS == 32
|
---|
| 170 | * // call win32 api.
|
---|
| 171 | * # endif // ARCH_BITS == 32
|
---|
| 172 | * #else // !RT_OS_WINDOWS
|
---|
| 173 | * // call posix api
|
---|
| 174 | * #endif // !RT_OS_WINDOWS
|
---|
| 175 | * @endcode
|
---|
| 176 | *
|
---|
| 177 | * - There are RT_OS_xxx defines for each OS, just like RT_OS_WINDOWS
|
---|
| 178 | * mentioned above. Use these defines instead of any predefined
|
---|
| 179 | * compiler stuff or defines from system headers.
|
---|
| 180 | *
|
---|
| 181 | * - RT_ARCH_X86 is defined when compiling for the x86 the architecture.
|
---|
| 182 | * Do not use __x86__, __X86__, __[Ii]386__, __[Ii]586__, or similar
|
---|
| 183 | * for this purpose.
|
---|
| 184 | *
|
---|
[16169] | 185 | * - RT_ARCH_AMD64 is defined when compiling for the AMD64 architecture.
|
---|
[6303] | 186 | * Do not use __AMD64__, __amd64__ or __x64_86__.
|
---|
| 187 | *
|
---|
| 188 | * - Take care and use size_t when you have to, esp. when passing a pointer
|
---|
| 189 | * to a size_t as a parameter.
|
---|
| 190 | *
|
---|
[9396] | 191 | * - Be wary of type promotion to (signed) integer. For example the
|
---|
| 192 | * following will cause u8 to be promoted to int in the shift, and then
|
---|
| 193 | * sign extended in the assignment 64-bit:
|
---|
| 194 | * @code
|
---|
| 195 | * uint8_t u8 = 0xfe;
|
---|
| 196 | * uint64_t u64 = u8 << 24;
|
---|
| 197 | * // u64 == 0xfffffffffe000000
|
---|
| 198 | * @endcode
|
---|
[6303] | 199 | *
|
---|
| 200 | *
|
---|
[21440] | 201 | * @subsection sec_vbox_guideline_compulsory_cppmain C++ guidelines for Main
|
---|
| 202 | *
|
---|
| 203 | * Main is currently (2009) full of hard-to-maintain code that uses complicated
|
---|
| 204 | * templates. The new mid-term goal for Main is to have less custom templates
|
---|
| 205 | * instead of more for the following reasons:
|
---|
| 206 | *
|
---|
| 207 | * - Template code is harder to read and understand. Custom templates create
|
---|
| 208 | * territories which only the code writer understands.
|
---|
| 209 | *
|
---|
| 210 | * - Errors in using templates create terrible C++ compiler messages.
|
---|
| 211 | *
|
---|
| 212 | * - Template code is really hard to look at in a debugger.
|
---|
| 213 | *
|
---|
| 214 | * - Templates slow down the compiler a lot.
|
---|
| 215 | *
|
---|
| 216 | * In particular, the following bits should be considered deprecated and should
|
---|
| 217 | * NOT be used in new code:
|
---|
| 218 | *
|
---|
| 219 | * - everything in include/iprt/cpputils.h (auto_ref_ptr, exception_trap_base,
|
---|
| 220 | * char_auto_ptr and friends)
|
---|
| 221 | *
|
---|
| 222 | * Generally, in many cases, a simple class with a proper destructor can achieve
|
---|
| 223 | * the same effect as a 1,000-line template include file, and the code is
|
---|
| 224 | * much more accessible that way.
|
---|
| 225 | *
|
---|
| 226 | * Using standard STL templates like std::list, std::vector and std::map is OK.
|
---|
| 227 | * Exceptions are:
|
---|
| 228 | *
|
---|
| 229 | * - Guest Additions because we don't want to link against libstdc++ there.
|
---|
| 230 | *
|
---|
| 231 | * - std::string should not be used because we have iprt::MiniString and
|
---|
| 232 | * com::Utf8Str which can convert efficiently with COM's UTF-16 strings.
|
---|
| 233 | *
|
---|
| 234 | * - std::auto_ptr<> in general; that part of the C++ standard is just broken.
|
---|
| 235 | * Write a destructor that calls delete.
|
---|
| 236 | *
|
---|
| 237 | *
|
---|
[26352] | 238 | * @subsection sec_vbox_guideline_compulsory_cppqtgui C++ guidelines for the Qt GUI
|
---|
[21449] | 239 | *
|
---|
[26352] | 240 | * The Qt GUI is currently (2010) on its way to become more compatible to the
|
---|
| 241 | * rest of VirtualBox coding style wise. From now on, all the coding style
|
---|
| 242 | * rules described in this file are also mandatory for the Qt GUI. Additionally
|
---|
| 243 | * the following rules should be respected:
|
---|
| 244 | *
|
---|
| 245 | * - GUI classes which correspond to GUI tasks should be prefixed by UI (no VBox anymore)
|
---|
| 246 | *
|
---|
| 247 | * - Classes which extents some of the Qt classes should be prefix by QI
|
---|
| 248 | *
|
---|
| 249 | * - General task classes should be prefixed by C
|
---|
| 250 | *
|
---|
| 251 | * - Slots are prefixed by slt -> sltName
|
---|
| 252 | *
|
---|
| 253 | * - Signals are prefixed by sig -> sigName
|
---|
| 254 | *
|
---|
| 255 | * - Use Qt classes for lists, strings and so on, the use of STL classes should
|
---|
| 256 | * be avoided
|
---|
| 257 | *
|
---|
| 258 | * - All files like .cpp, .h, .ui, which belong together are located in the
|
---|
| 259 | * same directory and named the same
|
---|
| 260 | *
|
---|
| 261 | *
|
---|
[53944] | 262 | * @subsection sec_vbox_guideline_compulsory_xslt XSLT
|
---|
| 263 | *
|
---|
| 264 | * XSLT (eXtensible Stylesheet Language Transformations) is used quite a bit in
|
---|
| 265 | * the Main API area of VirtualBox to generate sources and bindings to that API.
|
---|
| 266 | * There are a couple of common pitfalls worth mentioning:
|
---|
| 267 | *
|
---|
| 268 | * - Never do repeated //interface[@name=...] and //enum[@name=...] lookups
|
---|
| 269 | * because they are expensive. Instead delcare xsl:key elements for these
|
---|
| 270 | * searches and do the lookup using the key() function. xsltproc uses
|
---|
| 271 | * (per current document) hash tables for each xsl:key, i.e. very fast.
|
---|
| 272 | *
|
---|
| 273 | * - When output type is 'text' make sure to call xsltprocNewlineOutputHack
|
---|
| 274 | * from typemap-shared.inc.xsl every few KB of output, or xsltproc will
|
---|
| 275 | * end up wasting all the time reallocating the output buffer.
|
---|
| 276 | *
|
---|
| 277 | *
|
---|
[6303] | 278 | * @section sec_vbox_guideline_optional Optional
|
---|
| 279 | *
|
---|
[30954] | 280 | * First part is the actual coding style and all the prefixes. The second part
|
---|
[16169] | 281 | * is a bunch of good advice.
|
---|
[6303] | 282 | *
|
---|
| 283 | *
|
---|
| 284 | * @subsection sec_vbox_guideline_optional_layout The code layout
|
---|
| 285 | *
|
---|
[30954] | 286 | * - Max line length is 130 chars. Exceptions are table-like
|
---|
| 287 | * code/initializers and Log*() statements (don't waste unnecessary
|
---|
| 288 | * vertical space on debug logging).
|
---|
[6303] | 289 | *
|
---|
[44115] | 290 | * - Comments should try stay within the usual 80 columns as these are
|
---|
| 291 | * denser and too long lines may be harder to read.
|
---|
[6303] | 292 | *
|
---|
[30954] | 293 | * - Curly brackets are not indented. Example:
|
---|
[6303] | 294 | * @code
|
---|
[30954] | 295 | * if (true)
|
---|
| 296 | * {
|
---|
| 297 | * Something1();
|
---|
| 298 | * Something2();
|
---|
| 299 | * }
|
---|
| 300 | * else
|
---|
| 301 | * {
|
---|
| 302 | * SomethingElse1().
|
---|
| 303 | * SomethingElse2().
|
---|
| 304 | * }
|
---|
| 305 | * @endcode
|
---|
| 306 | *
|
---|
| 307 | * - Space before the parentheses when it comes after a C keyword.
|
---|
| 308 | *
|
---|
| 309 | * - No space between argument and parentheses. Exception for complex
|
---|
| 310 | * expression. Example:
|
---|
| 311 | * @code
|
---|
[6303] | 312 | * if (PATMR3IsPatchGCAddr(pVM, GCPtr))
|
---|
| 313 | * @endcode
|
---|
| 314 | *
|
---|
[16169] | 315 | * - The else of an if is always the first statement on a line. (No curly
|
---|
[6303] | 316 | * stuff before it!)
|
---|
| 317 | *
|
---|
[16169] | 318 | * - else and if go on the same line if no { compound statement }
|
---|
[30954] | 319 | * follows the if. Example:
|
---|
[6303] | 320 | * @code
|
---|
| 321 | * if (fFlags & MYFLAGS_1)
|
---|
| 322 | * fFlags &= ~MYFLAGS_10;
|
---|
| 323 | * else if (fFlags & MYFLAGS_2)
|
---|
| 324 | * {
|
---|
| 325 | * fFlags &= ~MYFLAGS_MASK;
|
---|
| 326 | * fFlags |= MYFLAGS_5;
|
---|
| 327 | * }
|
---|
| 328 | * else if (fFlags & MYFLAGS_3)
|
---|
| 329 | * @endcode
|
---|
| 330 | *
|
---|
| 331 | *
|
---|
[30954] | 332 | * - Slightly complex boolean expressions are split into multiple lines,
|
---|
| 333 | * putting the operators first on the line and indenting it all according
|
---|
| 334 | * to the nesting of the expression. The purpose is to make it as easy as
|
---|
| 335 | * possible to read. Example:
|
---|
| 336 | * @code
|
---|
| 337 | * if ( RT_SUCCESS(rc)
|
---|
| 338 | * || (fFlags & SOME_FLAG))
|
---|
| 339 | * @endcode
|
---|
| 340 | *
|
---|
| 341 | * - When 'if' or 'while' statements gets long, the closing parentheses
|
---|
| 342 | * goes right below the opening parentheses. This may be applied to
|
---|
| 343 | * sub-expression. Example:
|
---|
| 344 | * @code
|
---|
| 345 | * if ( RT_SUCCESS(rc)
|
---|
| 346 | * || ( fSomeStuff
|
---|
| 347 | * && fSomeOtherStuff
|
---|
| 348 | * && fEvenMoreStuff
|
---|
| 349 | * )
|
---|
| 350 | * || SomePredicateFunction()
|
---|
| 351 | * )
|
---|
| 352 | * {
|
---|
| 353 | * ...
|
---|
| 354 | * }
|
---|
| 355 | * @endcode
|
---|
| 356 | *
|
---|
| 357 | * - The case is indented from the switch (to avoid having the braces for
|
---|
| 358 | * the 'case' at the same level as the 'switch' statement).
|
---|
| 359 | *
|
---|
[6303] | 360 | * - If a case needs curly brackets they contain the entire case, are not
|
---|
| 361 | * indented from the case, and the break or return is placed inside them.
|
---|
| 362 | * Example:
|
---|
| 363 | * @code
|
---|
| 364 | * switch (pCur->eType)
|
---|
| 365 | * {
|
---|
| 366 | * case PGMMAPPINGTYPE_PAGETABLES:
|
---|
| 367 | * {
|
---|
| 368 | * unsigned iPDE = pCur->GCPtr >> PGDIR_SHIFT;
|
---|
| 369 | * unsigned iPT = (pCur->GCPtrEnd - pCur->GCPtr) >> PGDIR_SHIFT;
|
---|
| 370 | * while (iPT-- > 0)
|
---|
| 371 | * if (pPD->a[iPDE + iPT].n.u1Present)
|
---|
| 372 | * return VERR_HYPERVISOR_CONFLICT;
|
---|
| 373 | * break;
|
---|
| 374 | * }
|
---|
| 375 | * }
|
---|
| 376 | * @endcode
|
---|
| 377 | *
|
---|
| 378 | * - In a do while construction, the while is on the same line as the
|
---|
[16169] | 379 | * closing "}" if any are used.
|
---|
[6303] | 380 | * Example:
|
---|
| 381 | * @code
|
---|
| 382 | * do
|
---|
| 383 | * {
|
---|
| 384 | * stuff;
|
---|
| 385 | * i--;
|
---|
| 386 | * } while (i > 0);
|
---|
| 387 | * @endcode
|
---|
| 388 | *
|
---|
[30954] | 389 | * - Comments are in C style. C++ style comments are used for temporary
|
---|
[6303] | 390 | * disabling a few lines of code.
|
---|
| 391 | *
|
---|
| 392 | * - No unnecessary parentheses in expressions (just don't over do this
|
---|
| 393 | * so that gcc / msc starts bitching). Find a correct C/C++ operator
|
---|
| 394 | * precedence table if needed.
|
---|
| 395 | *
|
---|
[30954] | 396 | * - 'for (;;)' is preferred over 'while (true)' and 'while (1)'.
|
---|
[6303] | 397 | *
|
---|
[30954] | 398 | * - Parameters are indented to the start parentheses when breaking up
|
---|
| 399 | * function calls, declarations or prototypes. (This is in line with
|
---|
| 400 | * how 'if', 'for' and 'while' statements are done as well.) Example:
|
---|
| 401 | * @code
|
---|
| 402 | * RTPROCESS hProcess;
|
---|
| 403 | * int rc = RTProcCreateEx(papszArgs[0],
|
---|
| 404 | * papszArgs,
|
---|
| 405 | * RTENV_DEFAULT,
|
---|
| 406 | * fFlags,
|
---|
| 407 | * NULL, // phStdIn
|
---|
| 408 | * NULL, // phStdOut
|
---|
| 409 | * NULL, // phStdErr
|
---|
| 410 | * NULL, // pszAsUser
|
---|
| 411 | * NULL, // pszPassword
|
---|
| 412 | * &hProcess);
|
---|
| 413 | * @endcode
|
---|
| 414 | *
|
---|
| 415 | * - That Dijkstra is dead is no excuse for using gotos.
|
---|
| 416 | *
|
---|
| 417 | *
|
---|
| 418 | *
|
---|
[6303] | 419 | * @subsection sec_vbox_guideline_optional_prefix Variable / Member Prefixes
|
---|
| 420 | *
|
---|
[44115] | 421 | * Prefixes are meant to provide extra context clues to a variable/member, we
|
---|
| 422 | * therefore avoid using prefixes that just indicating the type if a better
|
---|
| 423 | * choice is available.
|
---|
| 424 | *
|
---|
| 425 | *
|
---|
| 426 | * The prefixes:
|
---|
| 427 | *
|
---|
[6303] | 428 | * - The 'g_' (or 'g') prefix means a global variable, either on file or module level.
|
---|
| 429 | *
|
---|
| 430 | * - The 's_' (or 's') prefix means a static variable inside a function or class.
|
---|
| 431 | *
|
---|
| 432 | * - The 'm_' (or 'm') prefix means a class data member.
|
---|
| 433 | *
|
---|
[30954] | 434 | * In new code in Main, use "m_" (and common sense). As an exception,
|
---|
| 435 | * in Main, if a class encapsulates its member variables in an anonymous
|
---|
[25113] | 436 | * structure which is declared in the class, but defined only in the
|
---|
[30954] | 437 | * implementation (like this: 'class X { struct Data; Data *m; }'), then
|
---|
| 438 | * the pointer to that struct is called 'm' itself and its members then
|
---|
| 439 | * need no prefix, because the members are accessed with 'm->member'
|
---|
| 440 | * already which is clear enough.
|
---|
[25113] | 441 | *
|
---|
[30954] | 442 | * - The 'a_' prefix means a parameter (argument) variable. This is
|
---|
| 443 | * sometimes written 'a' in parts of the source code that does not use
|
---|
| 444 | * the array prefix.
|
---|
[6303] | 445 | *
|
---|
[30954] | 446 | * - The 'p' prefix means pointer. For instance 'pVM' is pointer to VM.
|
---|
[6303] | 447 | *
|
---|
[30954] | 448 | * - The 'r' prefix means that something is passed by reference.
|
---|
[6303] | 449 | *
|
---|
[30954] | 450 | * - The 'k' prefix means that something is a constant. For instance
|
---|
| 451 | * 'enum { kStuff };'. This is usually not used in combination with
|
---|
| 452 | * 'p', 'r' or any such thing, it's main main use is to make enums
|
---|
| 453 | * easily identifiable.
|
---|
| 454 | *
|
---|
| 455 | * - The 'a' prefix means array. For instance 'aPages' could be read as
|
---|
| 456 | * array of pages.
|
---|
| 457 | *
|
---|
| 458 | * - The 'c' prefix means count. For instance 'cbBlock' could be read,
|
---|
| 459 | * count of bytes in block.
|
---|
| 460 | *
|
---|
[44115] | 461 | * - The 'cx' prefix means width (count of 'x' units).
|
---|
| 462 | *
|
---|
| 463 | * - The 'cy' prefix means height (count of 'y' units).
|
---|
| 464 | *
|
---|
| 465 | * - The 'x', 'y' and 'z' prefix refers to the x-, y- , and z-axis
|
---|
| 466 | * respectively.
|
---|
| 467 | *
|
---|
[6303] | 468 | * - The 'off' prefix means offset.
|
---|
| 469 | *
|
---|
[30954] | 470 | * - The 'i' or 'idx' prefixes usually means index. Although the 'i' one
|
---|
| 471 | * can sometimes just mean signed integer.
|
---|
[6303] | 472 | *
|
---|
[30954] | 473 | * - The 'i[1-9]+' prefix means a fixed bit size variable. Frequently
|
---|
[44115] | 474 | * used with the int[1-9]+_t types where the width is really important.
|
---|
| 475 | * In most cases 'i' is more appropriate. [type]
|
---|
[30954] | 476 | *
|
---|
[6303] | 477 | * - The 'e' (or 'enm') prefix means enum.
|
---|
| 478 | *
|
---|
[30954] | 479 | * - The 'u' prefix usually means unsigned integer. Exceptions follows.
|
---|
[6303] | 480 | *
|
---|
[30954] | 481 | * - The 'u[1-9]+' prefix means a fixed bit size variable. Frequently
|
---|
[44115] | 482 | * used with the uint[1-9]+_t types and with bitfields where the width is
|
---|
| 483 | * really important. In most cases 'u' or 'b' (byte) would be more
|
---|
| 484 | * appropriate. [type]
|
---|
[6303] | 485 | *
|
---|
[30954] | 486 | * - The 'b' prefix means byte or bytes. [type]
|
---|
[6303] | 487 | *
|
---|
[30954] | 488 | * - The 'f' prefix means flags. Flags are unsigned integers of some kind
|
---|
| 489 | * or booleans.
|
---|
[6303] | 490 | *
|
---|
[30954] | 491 | * - TODO: need prefix for real float. [type]
|
---|
[6303] | 492 | *
|
---|
[30954] | 493 | * - The 'rd' prefix means real double and is used for 'double' variables.
|
---|
| 494 | * [type]
|
---|
[6303] | 495 | *
|
---|
[30954] | 496 | * - The 'lrd' prefix means long real double and is used for 'long double'
|
---|
| 497 | * variables. [type]
|
---|
[6303] | 498 | *
|
---|
[30954] | 499 | * - The 'ch' prefix means a char, the (signed) char type. [type]
|
---|
[6303] | 500 | *
|
---|
[30954] | 501 | * - The 'wc' prefix means a wide/windows char, the RTUTF16 type. [type]
|
---|
[6303] | 502 | *
|
---|
[30954] | 503 | * - The 'uc' prefix means a Unicode Code point, the RTUNICP type. [type]
|
---|
[6303] | 504 | *
|
---|
[30954] | 505 | * - The 'uch' prefix means unsigned char. It's rarely used. [type]
|
---|
[6303] | 506 | *
|
---|
[30954] | 507 | * - The 'sz' prefix means zero terminated character string (array of
|
---|
| 508 | * chars). (UTF-8)
|
---|
| 509 | *
|
---|
| 510 | * - The 'wsz' prefix means zero terminated wide/windows character string
|
---|
| 511 | * (array of RTUTF16).
|
---|
| 512 | *
|
---|
| 513 | * - The 'usz' prefix means zero terminated Unicode string (array of
|
---|
| 514 | * RTUNICP).
|
---|
| 515 | *
|
---|
[26352] | 516 | * - The 'str' prefix means C++ string; either a std::string or, in Main,
|
---|
[30954] | 517 | * a Utf8Str or, in Qt, a QString. When used with 'p', 'r', 'a' or 'c'
|
---|
| 518 | * the first letter should be capitalized.
|
---|
[25113] | 519 | *
|
---|
[30954] | 520 | * - The 'bstr' prefix, in Main, means a UTF-16 Bstr. When used with 'p',
|
---|
| 521 | * 'r', 'a' or 'c' the first letter should be capitalized.
|
---|
[25113] | 522 | *
|
---|
[6303] | 523 | * - The 'pfn' prefix means pointer to function. Common usage is 'pfnCallback'
|
---|
| 524 | * and such like.
|
---|
| 525 | *
|
---|
[30954] | 526 | * - The 'psz' prefix is a combination of 'p' and 'sz' and thus means
|
---|
| 527 | * pointer to a zero terminated character string. (UTF-8)
|
---|
[6303] | 528 | *
|
---|
[30954] | 529 | * - The 'pcsz' prefix is used to indicate constant string pointers in
|
---|
| 530 | * parts of the code. Most code uses 'psz' for const and non-const
|
---|
| 531 | * string pointers.
|
---|
| 532 | *
|
---|
| 533 | * - The 'l' prefix means (signed) long. We try avoid using this,
|
---|
| 534 | * expecially with the 'LONG' types in Main as these are not 'long' on
|
---|
| 535 | * 64-bit non-Windows platforms and can cause confusion. Alternatives:
|
---|
| 536 | * 'i' or 'i32'. [type]
|
---|
| 537 | *
|
---|
| 538 | * - The 'ul' prefix means unsigned long. We try avoid using this,
|
---|
| 539 | * expecially with the 'ULONG' types in Main as these are not 'unsigned
|
---|
| 540 | * long' on 64-bit non-Windows platforms and can cause confusion.
|
---|
| 541 | * Alternatives: 'u' or 'u32'. [type]
|
---|
| 542 | *
|
---|
| 543 | *
|
---|
[6303] | 544 | * @subsection sec_vbox_guideline_optional_misc Misc / Advice / Stuff
|
---|
| 545 | *
|
---|
| 546 | * - When writing code think as the reader.
|
---|
| 547 | *
|
---|
[26668] | 548 | * - When writing code think as the compiler. (2)
|
---|
[6303] | 549 | *
|
---|
[16169] | 550 | * - When reading code think as if it's full of bugs - find them and fix them.
|
---|
[6303] | 551 | *
|
---|
| 552 | * - Pointer within range tests like:
|
---|
| 553 | * @code
|
---|
| 554 | * if ((uintptr_t)pv >= (uintptr_t)pvBase && (uintptr_t)pv < (uintptr_t)pvBase + cbRange)
|
---|
| 555 | * @endcode
|
---|
| 556 | * Can also be written as (assuming cbRange unsigned):
|
---|
| 557 | * @code
|
---|
| 558 | * if ((uintptr_t)pv - (uintptr_t)pvBase < cbRange)
|
---|
| 559 | * @endcode
|
---|
| 560 | * Which is shorter and potentially faster. (1)
|
---|
| 561 | *
|
---|
[16169] | 562 | * - Avoid unnecessary casting. All pointers automatically cast down to
|
---|
| 563 | * void *, at least for non class instance pointers.
|
---|
[6303] | 564 | *
|
---|
| 565 | * - It's very very bad practise to write a function larger than a
|
---|
[16169] | 566 | * screen full (1024x768) without any comprehensibility and explaining
|
---|
| 567 | * comments.
|
---|
[6303] | 568 | *
|
---|
| 569 | * - More to come....
|
---|
| 570 | *
|
---|
| 571 | *
|
---|
| 572 | * (1) Important, be very careful with the casting. In particular, note that
|
---|
| 573 | * a compiler might treat pointers as signed (IIRC).
|
---|
| 574 | *
|
---|
[26668] | 575 | * (2) "A really advanced hacker comes to understand the true inner workings of
|
---|
| 576 | * the machine - he sees through the language he's working in and glimpses
|
---|
| 577 | * the secret functioning of the binary code - becomes a Ba'al Shem of
|
---|
| 578 | * sorts." (Neal Stephenson "Snow Crash")
|
---|
[6303] | 579 | *
|
---|
| 580 | *
|
---|
| 581 | *
|
---|
| 582 | * @section sec_vbox_guideline_warnings Compiler Warnings
|
---|
| 583 | *
|
---|
| 584 | * The code should when possible compile on all platforms and compilers without any
|
---|
| 585 | * warnings. That's a nice idea, however, if it means making the code harder to read,
|
---|
| 586 | * less portable, unreliable or similar, the warning should not be fixed.
|
---|
| 587 | *
|
---|
| 588 | * Some of the warnings can seem kind of innocent at first glance. So, let's take the
|
---|
| 589 | * most common ones and explain them.
|
---|
| 590 | *
|
---|
[21449] | 591 | *
|
---|
[6303] | 592 | * @subsection sec_vbox_guideline_warnings_signed_unsigned_compare Signed / Unsigned Compare
|
---|
| 593 | *
|
---|
| 594 | * GCC says: "warning: comparison between signed and unsigned integer expressions"
|
---|
| 595 | * MSC says: "warning C4018: '<|<=|==|>=|>' : signed/unsigned mismatch"
|
---|
| 596 | *
|
---|
| 597 | * The following example will not output what you expect:
|
---|
| 598 | @code
|
---|
| 599 | #include <stdio.h>
|
---|
| 600 | int main()
|
---|
| 601 | {
|
---|
| 602 | signed long a = -1;
|
---|
| 603 | unsigned long b = 2294967295;
|
---|
| 604 | if (a < b)
|
---|
| 605 | printf("%ld < %lu: true\n", a, b);
|
---|
| 606 | else
|
---|
| 607 | printf("%ld < %lu: false\n", a, b);
|
---|
| 608 | return 0;
|
---|
| 609 | }
|
---|
| 610 | @endcode
|
---|
[16169] | 611 | * If I understood it correctly, the compiler will convert a to an
|
---|
| 612 | * unsigned long before doing the compare.
|
---|
[6303] | 613 | *
|
---|
| 614 | *
|
---|
[21449] | 615 | *
|
---|
[6303] | 616 | * @section sec_vbox_guideline_svn Subversion Commit Rules
|
---|
| 617 | *
|
---|
| 618 | *
|
---|
| 619 | * Before checking in:
|
---|
| 620 | *
|
---|
| 621 | * - Check Tinderbox and make sure the tree is green across all platforms. If it's
|
---|
| 622 | * red on a platform, don't check in. If you want, warn in the \#vbox channel and
|
---|
| 623 | * help make the responsible person fix it.
|
---|
| 624 | * NEVER CHECK IN TO A BROKEN BUILD.
|
---|
| 625 | *
|
---|
[16169] | 626 | * - When checking in keep in mind that a commit is atomic and that the Tinderbox and
|
---|
[6303] | 627 | * developers are constantly checking out the tree. Therefore do not split up the
|
---|
[16169] | 628 | * commit unless it's into 100% independent parts. If you need to split it up in order
|
---|
[6303] | 629 | * to have sensible commit comments, make the sub-commits as rapid as possible.
|
---|
| 630 | *
|
---|
[16169] | 631 | * - If you make a user visible change, such as fixing a reported bug,
|
---|
| 632 | * make sure you add an entry to doc/manual/user_ChangeLogImpl.xml.
|
---|
[6303] | 633 | *
|
---|
[21449] | 634 | * - If you are adding files make sure set the right attributes.
|
---|
| 635 | * svn-ps.sh/cmd was created for this purpose, please make use of it.
|
---|
[6303] | 636 | *
|
---|
[21449] | 637 | *
|
---|
[6303] | 638 | * After checking in:
|
---|
| 639 | *
|
---|
| 640 | * - After checking-in, you watch Tinderbox until your check-ins clear. You do not
|
---|
| 641 | * go home. You do not sleep. You do not log out or experiment with drugs. You do
|
---|
| 642 | * not become unavailable. If you break the tree, add a comment saying that you're
|
---|
| 643 | * fixing it. If you can't fix it and need help, ask in the \#innotek channel or back
|
---|
| 644 | * out the change.
|
---|
| 645 | *
|
---|
| 646 | * (Inspired by mozilla tree rules.)
|
---|
| 647 | */
|
---|
| 648 |
|
---|