[19010] | 1 | /* $Id: VBox-CodingGuidelines.cpp 44528 2013-02-04 14:27:54Z 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 | *
|
---|
[6303] | 262 | * @section sec_vbox_guideline_optional Optional
|
---|
| 263 | *
|
---|
[30954] | 264 | * First part is the actual coding style and all the prefixes. The second part
|
---|
[16169] | 265 | * is a bunch of good advice.
|
---|
[6303] | 266 | *
|
---|
| 267 | *
|
---|
| 268 | * @subsection sec_vbox_guideline_optional_layout The code layout
|
---|
| 269 | *
|
---|
[30954] | 270 | * - Max line length is 130 chars. Exceptions are table-like
|
---|
| 271 | * code/initializers and Log*() statements (don't waste unnecessary
|
---|
| 272 | * vertical space on debug logging).
|
---|
[6303] | 273 | *
|
---|
[44115] | 274 | * - Comments should try stay within the usual 80 columns as these are
|
---|
| 275 | * denser and too long lines may be harder to read.
|
---|
[6303] | 276 | *
|
---|
[30954] | 277 | * - Curly brackets are not indented. Example:
|
---|
[6303] | 278 | * @code
|
---|
[30954] | 279 | * if (true)
|
---|
| 280 | * {
|
---|
| 281 | * Something1();
|
---|
| 282 | * Something2();
|
---|
| 283 | * }
|
---|
| 284 | * else
|
---|
| 285 | * {
|
---|
| 286 | * SomethingElse1().
|
---|
| 287 | * SomethingElse2().
|
---|
| 288 | * }
|
---|
| 289 | * @endcode
|
---|
| 290 | *
|
---|
| 291 | * - Space before the parentheses when it comes after a C keyword.
|
---|
| 292 | *
|
---|
| 293 | * - No space between argument and parentheses. Exception for complex
|
---|
| 294 | * expression. Example:
|
---|
| 295 | * @code
|
---|
[6303] | 296 | * if (PATMR3IsPatchGCAddr(pVM, GCPtr))
|
---|
| 297 | * @endcode
|
---|
| 298 | *
|
---|
[16169] | 299 | * - The else of an if is always the first statement on a line. (No curly
|
---|
[6303] | 300 | * stuff before it!)
|
---|
| 301 | *
|
---|
[16169] | 302 | * - else and if go on the same line if no { compound statement }
|
---|
[30954] | 303 | * follows the if. Example:
|
---|
[6303] | 304 | * @code
|
---|
| 305 | * if (fFlags & MYFLAGS_1)
|
---|
| 306 | * fFlags &= ~MYFLAGS_10;
|
---|
| 307 | * else if (fFlags & MYFLAGS_2)
|
---|
| 308 | * {
|
---|
| 309 | * fFlags &= ~MYFLAGS_MASK;
|
---|
| 310 | * fFlags |= MYFLAGS_5;
|
---|
| 311 | * }
|
---|
| 312 | * else if (fFlags & MYFLAGS_3)
|
---|
| 313 | * @endcode
|
---|
| 314 | *
|
---|
| 315 | *
|
---|
[30954] | 316 | * - Slightly complex boolean expressions are split into multiple lines,
|
---|
| 317 | * putting the operators first on the line and indenting it all according
|
---|
| 318 | * to the nesting of the expression. The purpose is to make it as easy as
|
---|
| 319 | * possible to read. Example:
|
---|
| 320 | * @code
|
---|
| 321 | * if ( RT_SUCCESS(rc)
|
---|
| 322 | * || (fFlags & SOME_FLAG))
|
---|
| 323 | * @endcode
|
---|
| 324 | *
|
---|
| 325 | * - When 'if' or 'while' statements gets long, the closing parentheses
|
---|
| 326 | * goes right below the opening parentheses. This may be applied to
|
---|
| 327 | * sub-expression. Example:
|
---|
| 328 | * @code
|
---|
| 329 | * if ( RT_SUCCESS(rc)
|
---|
| 330 | * || ( fSomeStuff
|
---|
| 331 | * && fSomeOtherStuff
|
---|
| 332 | * && fEvenMoreStuff
|
---|
| 333 | * )
|
---|
| 334 | * || SomePredicateFunction()
|
---|
| 335 | * )
|
---|
| 336 | * {
|
---|
| 337 | * ...
|
---|
| 338 | * }
|
---|
| 339 | * @endcode
|
---|
| 340 | *
|
---|
| 341 | * - The case is indented from the switch (to avoid having the braces for
|
---|
| 342 | * the 'case' at the same level as the 'switch' statement).
|
---|
| 343 | *
|
---|
[6303] | 344 | * - If a case needs curly brackets they contain the entire case, are not
|
---|
| 345 | * indented from the case, and the break or return is placed inside them.
|
---|
| 346 | * Example:
|
---|
| 347 | * @code
|
---|
| 348 | * switch (pCur->eType)
|
---|
| 349 | * {
|
---|
| 350 | * case PGMMAPPINGTYPE_PAGETABLES:
|
---|
| 351 | * {
|
---|
| 352 | * unsigned iPDE = pCur->GCPtr >> PGDIR_SHIFT;
|
---|
| 353 | * unsigned iPT = (pCur->GCPtrEnd - pCur->GCPtr) >> PGDIR_SHIFT;
|
---|
| 354 | * while (iPT-- > 0)
|
---|
| 355 | * if (pPD->a[iPDE + iPT].n.u1Present)
|
---|
| 356 | * return VERR_HYPERVISOR_CONFLICT;
|
---|
| 357 | * break;
|
---|
| 358 | * }
|
---|
| 359 | * }
|
---|
| 360 | * @endcode
|
---|
| 361 | *
|
---|
| 362 | * - In a do while construction, the while is on the same line as the
|
---|
[16169] | 363 | * closing "}" if any are used.
|
---|
[6303] | 364 | * Example:
|
---|
| 365 | * @code
|
---|
| 366 | * do
|
---|
| 367 | * {
|
---|
| 368 | * stuff;
|
---|
| 369 | * i--;
|
---|
| 370 | * } while (i > 0);
|
---|
| 371 | * @endcode
|
---|
| 372 | *
|
---|
[30954] | 373 | * - Comments are in C style. C++ style comments are used for temporary
|
---|
[6303] | 374 | * disabling a few lines of code.
|
---|
| 375 | *
|
---|
| 376 | * - No unnecessary parentheses in expressions (just don't over do this
|
---|
| 377 | * so that gcc / msc starts bitching). Find a correct C/C++ operator
|
---|
| 378 | * precedence table if needed.
|
---|
| 379 | *
|
---|
[30954] | 380 | * - 'for (;;)' is preferred over 'while (true)' and 'while (1)'.
|
---|
[6303] | 381 | *
|
---|
[30954] | 382 | * - Parameters are indented to the start parentheses when breaking up
|
---|
| 383 | * function calls, declarations or prototypes. (This is in line with
|
---|
| 384 | * how 'if', 'for' and 'while' statements are done as well.) Example:
|
---|
| 385 | * @code
|
---|
| 386 | * RTPROCESS hProcess;
|
---|
| 387 | * int rc = RTProcCreateEx(papszArgs[0],
|
---|
| 388 | * papszArgs,
|
---|
| 389 | * RTENV_DEFAULT,
|
---|
| 390 | * fFlags,
|
---|
| 391 | * NULL, // phStdIn
|
---|
| 392 | * NULL, // phStdOut
|
---|
| 393 | * NULL, // phStdErr
|
---|
| 394 | * NULL, // pszAsUser
|
---|
| 395 | * NULL, // pszPassword
|
---|
| 396 | * &hProcess);
|
---|
| 397 | * @endcode
|
---|
| 398 | *
|
---|
| 399 | * - That Dijkstra is dead is no excuse for using gotos.
|
---|
| 400 | *
|
---|
| 401 | *
|
---|
| 402 | *
|
---|
[6303] | 403 | * @subsection sec_vbox_guideline_optional_prefix Variable / Member Prefixes
|
---|
| 404 | *
|
---|
[44115] | 405 | * Prefixes are meant to provide extra context clues to a variable/member, we
|
---|
| 406 | * therefore avoid using prefixes that just indicating the type if a better
|
---|
| 407 | * choice is available.
|
---|
| 408 | *
|
---|
| 409 | *
|
---|
| 410 | * The prefixes:
|
---|
| 411 | *
|
---|
[6303] | 412 | * - The 'g_' (or 'g') prefix means a global variable, either on file or module level.
|
---|
| 413 | *
|
---|
| 414 | * - The 's_' (or 's') prefix means a static variable inside a function or class.
|
---|
| 415 | *
|
---|
| 416 | * - The 'm_' (or 'm') prefix means a class data member.
|
---|
| 417 | *
|
---|
[30954] | 418 | * In new code in Main, use "m_" (and common sense). As an exception,
|
---|
| 419 | * in Main, if a class encapsulates its member variables in an anonymous
|
---|
[25113] | 420 | * structure which is declared in the class, but defined only in the
|
---|
[30954] | 421 | * implementation (like this: 'class X { struct Data; Data *m; }'), then
|
---|
| 422 | * the pointer to that struct is called 'm' itself and its members then
|
---|
| 423 | * need no prefix, because the members are accessed with 'm->member'
|
---|
| 424 | * already which is clear enough.
|
---|
[25113] | 425 | *
|
---|
[30954] | 426 | * - The 'a_' prefix means a parameter (argument) variable. This is
|
---|
| 427 | * sometimes written 'a' in parts of the source code that does not use
|
---|
| 428 | * the array prefix.
|
---|
[6303] | 429 | *
|
---|
[30954] | 430 | * - The 'p' prefix means pointer. For instance 'pVM' is pointer to VM.
|
---|
[6303] | 431 | *
|
---|
[30954] | 432 | * - The 'r' prefix means that something is passed by reference.
|
---|
[6303] | 433 | *
|
---|
[30954] | 434 | * - The 'k' prefix means that something is a constant. For instance
|
---|
| 435 | * 'enum { kStuff };'. This is usually not used in combination with
|
---|
| 436 | * 'p', 'r' or any such thing, it's main main use is to make enums
|
---|
| 437 | * easily identifiable.
|
---|
| 438 | *
|
---|
| 439 | * - The 'a' prefix means array. For instance 'aPages' could be read as
|
---|
| 440 | * array of pages.
|
---|
| 441 | *
|
---|
| 442 | * - The 'c' prefix means count. For instance 'cbBlock' could be read,
|
---|
| 443 | * count of bytes in block.
|
---|
| 444 | *
|
---|
[44115] | 445 | * - The 'cx' prefix means width (count of 'x' units).
|
---|
| 446 | *
|
---|
| 447 | * - The 'cy' prefix means height (count of 'y' units).
|
---|
| 448 | *
|
---|
| 449 | * - The 'x', 'y' and 'z' prefix refers to the x-, y- , and z-axis
|
---|
| 450 | * respectively.
|
---|
| 451 | *
|
---|
[6303] | 452 | * - The 'off' prefix means offset.
|
---|
| 453 | *
|
---|
[30954] | 454 | * - The 'i' or 'idx' prefixes usually means index. Although the 'i' one
|
---|
| 455 | * can sometimes just mean signed integer.
|
---|
[6303] | 456 | *
|
---|
[30954] | 457 | * - The 'i[1-9]+' prefix means a fixed bit size variable. Frequently
|
---|
[44115] | 458 | * used with the int[1-9]+_t types where the width is really important.
|
---|
| 459 | * In most cases 'i' is more appropriate. [type]
|
---|
[30954] | 460 | *
|
---|
[6303] | 461 | * - The 'e' (or 'enm') prefix means enum.
|
---|
| 462 | *
|
---|
[30954] | 463 | * - The 'u' prefix usually means unsigned integer. Exceptions follows.
|
---|
[6303] | 464 | *
|
---|
[30954] | 465 | * - The 'u[1-9]+' prefix means a fixed bit size variable. Frequently
|
---|
[44115] | 466 | * used with the uint[1-9]+_t types and with bitfields where the width is
|
---|
| 467 | * really important. In most cases 'u' or 'b' (byte) would be more
|
---|
| 468 | * appropriate. [type]
|
---|
[6303] | 469 | *
|
---|
[30954] | 470 | * - The 'b' prefix means byte or bytes. [type]
|
---|
[6303] | 471 | *
|
---|
[30954] | 472 | * - The 'f' prefix means flags. Flags are unsigned integers of some kind
|
---|
| 473 | * or booleans.
|
---|
[6303] | 474 | *
|
---|
[30954] | 475 | * - TODO: need prefix for real float. [type]
|
---|
[6303] | 476 | *
|
---|
[30954] | 477 | * - The 'rd' prefix means real double and is used for 'double' variables.
|
---|
| 478 | * [type]
|
---|
[6303] | 479 | *
|
---|
[30954] | 480 | * - The 'lrd' prefix means long real double and is used for 'long double'
|
---|
| 481 | * variables. [type]
|
---|
[6303] | 482 | *
|
---|
[30954] | 483 | * - The 'ch' prefix means a char, the (signed) char type. [type]
|
---|
[6303] | 484 | *
|
---|
[30954] | 485 | * - The 'wc' prefix means a wide/windows char, the RTUTF16 type. [type]
|
---|
[6303] | 486 | *
|
---|
[30954] | 487 | * - The 'uc' prefix means a Unicode Code point, the RTUNICP type. [type]
|
---|
[6303] | 488 | *
|
---|
[30954] | 489 | * - The 'uch' prefix means unsigned char. It's rarely used. [type]
|
---|
[6303] | 490 | *
|
---|
[30954] | 491 | * - The 'sz' prefix means zero terminated character string (array of
|
---|
| 492 | * chars). (UTF-8)
|
---|
| 493 | *
|
---|
| 494 | * - The 'wsz' prefix means zero terminated wide/windows character string
|
---|
| 495 | * (array of RTUTF16).
|
---|
| 496 | *
|
---|
| 497 | * - The 'usz' prefix means zero terminated Unicode string (array of
|
---|
| 498 | * RTUNICP).
|
---|
| 499 | *
|
---|
[26352] | 500 | * - The 'str' prefix means C++ string; either a std::string or, in Main,
|
---|
[30954] | 501 | * a Utf8Str or, in Qt, a QString. When used with 'p', 'r', 'a' or 'c'
|
---|
| 502 | * the first letter should be capitalized.
|
---|
[25113] | 503 | *
|
---|
[30954] | 504 | * - The 'bstr' prefix, in Main, means a UTF-16 Bstr. When used with 'p',
|
---|
| 505 | * 'r', 'a' or 'c' the first letter should be capitalized.
|
---|
[25113] | 506 | *
|
---|
[6303] | 507 | * - The 'pfn' prefix means pointer to function. Common usage is 'pfnCallback'
|
---|
| 508 | * and such like.
|
---|
| 509 | *
|
---|
[30954] | 510 | * - The 'psz' prefix is a combination of 'p' and 'sz' and thus means
|
---|
| 511 | * pointer to a zero terminated character string. (UTF-8)
|
---|
[6303] | 512 | *
|
---|
[30954] | 513 | * - The 'pcsz' prefix is used to indicate constant string pointers in
|
---|
| 514 | * parts of the code. Most code uses 'psz' for const and non-const
|
---|
| 515 | * string pointers.
|
---|
| 516 | *
|
---|
| 517 | * - The 'l' prefix means (signed) long. We try avoid using this,
|
---|
| 518 | * expecially with the 'LONG' types in Main as these are not 'long' on
|
---|
| 519 | * 64-bit non-Windows platforms and can cause confusion. Alternatives:
|
---|
| 520 | * 'i' or 'i32'. [type]
|
---|
| 521 | *
|
---|
| 522 | * - The 'ul' prefix means unsigned long. We try avoid using this,
|
---|
| 523 | * expecially with the 'ULONG' types in Main as these are not 'unsigned
|
---|
| 524 | * long' on 64-bit non-Windows platforms and can cause confusion.
|
---|
| 525 | * Alternatives: 'u' or 'u32'. [type]
|
---|
| 526 | *
|
---|
| 527 | *
|
---|
[6303] | 528 | * @subsection sec_vbox_guideline_optional_misc Misc / Advice / Stuff
|
---|
| 529 | *
|
---|
| 530 | * - When writing code think as the reader.
|
---|
| 531 | *
|
---|
[26668] | 532 | * - When writing code think as the compiler. (2)
|
---|
[6303] | 533 | *
|
---|
[16169] | 534 | * - When reading code think as if it's full of bugs - find them and fix them.
|
---|
[6303] | 535 | *
|
---|
| 536 | * - Pointer within range tests like:
|
---|
| 537 | * @code
|
---|
| 538 | * if ((uintptr_t)pv >= (uintptr_t)pvBase && (uintptr_t)pv < (uintptr_t)pvBase + cbRange)
|
---|
| 539 | * @endcode
|
---|
| 540 | * Can also be written as (assuming cbRange unsigned):
|
---|
| 541 | * @code
|
---|
| 542 | * if ((uintptr_t)pv - (uintptr_t)pvBase < cbRange)
|
---|
| 543 | * @endcode
|
---|
| 544 | * Which is shorter and potentially faster. (1)
|
---|
| 545 | *
|
---|
[16169] | 546 | * - Avoid unnecessary casting. All pointers automatically cast down to
|
---|
| 547 | * void *, at least for non class instance pointers.
|
---|
[6303] | 548 | *
|
---|
| 549 | * - It's very very bad practise to write a function larger than a
|
---|
[16169] | 550 | * screen full (1024x768) without any comprehensibility and explaining
|
---|
| 551 | * comments.
|
---|
[6303] | 552 | *
|
---|
| 553 | * - More to come....
|
---|
| 554 | *
|
---|
| 555 | *
|
---|
| 556 | * (1) Important, be very careful with the casting. In particular, note that
|
---|
| 557 | * a compiler might treat pointers as signed (IIRC).
|
---|
| 558 | *
|
---|
[26668] | 559 | * (2) "A really advanced hacker comes to understand the true inner workings of
|
---|
| 560 | * the machine - he sees through the language he's working in and glimpses
|
---|
| 561 | * the secret functioning of the binary code - becomes a Ba'al Shem of
|
---|
| 562 | * sorts." (Neal Stephenson "Snow Crash")
|
---|
[6303] | 563 | *
|
---|
| 564 | *
|
---|
| 565 | *
|
---|
| 566 | * @section sec_vbox_guideline_warnings Compiler Warnings
|
---|
| 567 | *
|
---|
| 568 | * The code should when possible compile on all platforms and compilers without any
|
---|
| 569 | * warnings. That's a nice idea, however, if it means making the code harder to read,
|
---|
| 570 | * less portable, unreliable or similar, the warning should not be fixed.
|
---|
| 571 | *
|
---|
| 572 | * Some of the warnings can seem kind of innocent at first glance. So, let's take the
|
---|
| 573 | * most common ones and explain them.
|
---|
| 574 | *
|
---|
[21449] | 575 | *
|
---|
[6303] | 576 | * @subsection sec_vbox_guideline_warnings_signed_unsigned_compare Signed / Unsigned Compare
|
---|
| 577 | *
|
---|
| 578 | * GCC says: "warning: comparison between signed and unsigned integer expressions"
|
---|
| 579 | * MSC says: "warning C4018: '<|<=|==|>=|>' : signed/unsigned mismatch"
|
---|
| 580 | *
|
---|
| 581 | * The following example will not output what you expect:
|
---|
| 582 | @code
|
---|
| 583 | #include <stdio.h>
|
---|
| 584 | int main()
|
---|
| 585 | {
|
---|
| 586 | signed long a = -1;
|
---|
| 587 | unsigned long b = 2294967295;
|
---|
| 588 | if (a < b)
|
---|
| 589 | printf("%ld < %lu: true\n", a, b);
|
---|
| 590 | else
|
---|
| 591 | printf("%ld < %lu: false\n", a, b);
|
---|
| 592 | return 0;
|
---|
| 593 | }
|
---|
| 594 | @endcode
|
---|
[16169] | 595 | * If I understood it correctly, the compiler will convert a to an
|
---|
| 596 | * unsigned long before doing the compare.
|
---|
[6303] | 597 | *
|
---|
| 598 | *
|
---|
[21449] | 599 | *
|
---|
[6303] | 600 | * @section sec_vbox_guideline_svn Subversion Commit Rules
|
---|
| 601 | *
|
---|
| 602 | *
|
---|
| 603 | * Before checking in:
|
---|
| 604 | *
|
---|
| 605 | * - Check Tinderbox and make sure the tree is green across all platforms. If it's
|
---|
| 606 | * red on a platform, don't check in. If you want, warn in the \#vbox channel and
|
---|
| 607 | * help make the responsible person fix it.
|
---|
| 608 | * NEVER CHECK IN TO A BROKEN BUILD.
|
---|
| 609 | *
|
---|
[16169] | 610 | * - When checking in keep in mind that a commit is atomic and that the Tinderbox and
|
---|
[6303] | 611 | * developers are constantly checking out the tree. Therefore do not split up the
|
---|
[16169] | 612 | * commit unless it's into 100% independent parts. If you need to split it up in order
|
---|
[6303] | 613 | * to have sensible commit comments, make the sub-commits as rapid as possible.
|
---|
| 614 | *
|
---|
[16169] | 615 | * - If you make a user visible change, such as fixing a reported bug,
|
---|
| 616 | * make sure you add an entry to doc/manual/user_ChangeLogImpl.xml.
|
---|
[6303] | 617 | *
|
---|
[21449] | 618 | * - If you are adding files make sure set the right attributes.
|
---|
| 619 | * svn-ps.sh/cmd was created for this purpose, please make use of it.
|
---|
[6303] | 620 | *
|
---|
[21449] | 621 | *
|
---|
[6303] | 622 | * After checking in:
|
---|
| 623 | *
|
---|
| 624 | * - After checking-in, you watch Tinderbox until your check-ins clear. You do not
|
---|
| 625 | * go home. You do not sleep. You do not log out or experiment with drugs. You do
|
---|
| 626 | * not become unavailable. If you break the tree, add a comment saying that you're
|
---|
| 627 | * fixing it. If you can't fix it and need help, ask in the \#innotek channel or back
|
---|
| 628 | * out the change.
|
---|
| 629 | *
|
---|
| 630 | * (Inspired by mozilla tree rules.)
|
---|
| 631 | */
|
---|
| 632 |
|
---|