173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * VBox - Coding Guidelines.
c58f1213e628a545081c70e26c6b67a841cff880vboxsync * Copyright (C) 2006-2012 Oracle Corporation
1c94c0a63ba68be1a7b2c640e70d7a06464e4fcavboxsync * This file is part of VirtualBox Open Source Edition (OSE), as
1c94c0a63ba68be1a7b2c640e70d7a06464e4fcavboxsync * available from http://www.virtualbox.org. This file is free software;
1c94c0a63ba68be1a7b2c640e70d7a06464e4fcavboxsync * you can redistribute it and/or modify it under the terms of the GNU
1c94c0a63ba68be1a7b2c640e70d7a06464e4fcavboxsync * General Public License (GPL) as published by the Free Software
1c94c0a63ba68be1a7b2c640e70d7a06464e4fcavboxsync * Foundation, in version 2 as it comes in the "COPYING" file of the
1c94c0a63ba68be1a7b2c640e70d7a06464e4fcavboxsync * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
1c94c0a63ba68be1a7b2c640e70d7a06464e4fcavboxsync * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync/** @page pg_vbox_guideline VBox Coding Guidelines
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * The VBox Coding guidelines are followed by all of VBox with the exception of
857dbac5b1cb353bf11b4b335443f51e63c4d29fvboxsync * qemu. Qemu is using whatever the frenchman does.
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * There are a few compulsory rules and a bunch of optional ones. The following
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * sections will describe these in details. In addition there is a section of
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * Subversion 'rules'.
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * @section sec_vbox_guideline_compulsory Compulsory
cc9afa50617a487414e35811204aa80bf06c565cvboxsync * - The indentation size is 4 chars.
cc9afa50617a487414e35811204aa80bf06c565cvboxsync * - Tabs are only ever used in makefiles.
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * - Use RT and VBOX types.
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * - Use Runtime functions.
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * - Use the standard bool, uintptr_t, intptr_t and [u]int[1-9+]_t types.
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * - Avoid using plain unsigned and int.
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * - Use static wherever possible. This makes the namespace less polluted
aaf3c5b4cbb2680c74acd426c2802e5d536d81f6vboxsync * and avoids nasty name clash problems which can occur, especially on
aaf3c5b4cbb2680c74acd426c2802e5d536d81f6vboxsync * Unix-like systems. (1)
aaf3c5b4cbb2680c74acd426c2802e5d536d81f6vboxsync * - Public names are of the form Domain[Subdomain[]]Method, using mixed
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * casing to mark the words. The main domain is all uppercase.
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * (Think like java, mapping domain and subdomain to packages/classes.)
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * - Public names are always declared using the appropriate DECL macro. (2)
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * - Internal names starts with a lowercased main domain.
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * - Defines are all uppercase and separate words with underscore.
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * This applies to enum values too.
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * - Typedefs are all uppercase and contain no underscores to distinguish
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * them from defines.
a8a5fcde141c804932506d0c09088bfe66a9f111vboxsync * - Pointer typedefs start with 'P'. If pointer to const then 'PC'.
a8a5fcde141c804932506d0c09088bfe66a9f111vboxsync * - Function typedefs start with 'FN'. If pointer to FN then 'PFN'.
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * - All files are case sensitive.
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * - Slashes are unix slashes ('/') runtime converts when necessary.
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * - char strings are UTF-8.
a8a5fcde141c804932506d0c09088bfe66a9f111vboxsync * - All functions return VBox status codes. There are three general
a8a5fcde141c804932506d0c09088bfe66a9f111vboxsync * exceptions from this:
a8a5fcde141c804932506d0c09088bfe66a9f111vboxsync * -# Predicate functions. These are function which are boolean in
a8a5fcde141c804932506d0c09088bfe66a9f111vboxsync * nature and usage. They return bool. The function name will
a8a5fcde141c804932506d0c09088bfe66a9f111vboxsync * include 'Has', 'Is' or similar.
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * -# Functions which by nature cannot possibly fail.
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * These return void.
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * -# "Get"-functions which return what they ask for.
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * A get function becomes a "Query" function if there is any
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * doubt about getting what is ask for.
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * - VBox status codes have three subdivisions:
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * -# Errors, which are VERR_ prefixed and negative.
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * -# Warnings, which are VWRN_ prefixed and positive.
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * -# Informational, which are VINF_ prefixed and positive.
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * - Platform/OS operation are generalized and put in the IPRT.
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * - Other useful constructs are also put in the IPRT.
a8a5fcde141c804932506d0c09088bfe66a9f111vboxsync * - The code shall not cause compiler warnings. Check this on ALL
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * the platforms.
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * - All files have file headers with $Id and a file tag which describes
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * the file in a sentence or two.
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * Note: Remember to enable keyword expansion when adding files to svn.
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * - All public functions are fully documented in Doxygen style using the
a8a5fcde141c804932506d0c09088bfe66a9f111vboxsync * javadoc dialect (using the 'at' instead of the 'slash' as
a8a5fcde141c804932506d0c09088bfe66a9f111vboxsync * commandprefix.)
a8a5fcde141c804932506d0c09088bfe66a9f111vboxsync * - All structures in header files are described, including all their
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * - All modules have a documentation 'page' in the main source file which
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * describes the intent and actual implementation.
a8a5fcde141c804932506d0c09088bfe66a9f111vboxsync * - Code which is doing things that are not immediately comprehensible
a8a5fcde141c804932506d0c09088bfe66a9f111vboxsync * shall include explanatory comments.
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * - Documentation and comments are kept up to date.
a8a5fcde141c804932506d0c09088bfe66a9f111vboxsync * - Headers in /include/VBox shall not contain any slash-slash C++
a8a5fcde141c804932506d0c09088bfe66a9f111vboxsync * comments, only ANSI C comments!
6829fa7e057359ac605f0b391676bfa338a8b818vboxsync * - Comments on \#else indicates what begins while the comment on a
6829fa7e057359ac605f0b391676bfa338a8b818vboxsync * \#endif indicates what ended.
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * (1) It is common practice on Unix to have a single symbol namespace for an
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * entire process. If one is careless symbols might be resolved in a
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * different way that one expects, leading to weird problems.
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * (2) This is common practice among most projects dealing with modules in
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * shared libraries. The Windows / PE __declspect(import) and
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * __declspect(export) constructs are the main reason for this.
a8a5fcde141c804932506d0c09088bfe66a9f111vboxsync * OTOH, we do perhaps have a bit too detailed graining of this in VMM...
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * @subsection sec_vbox_guideline_compulsory_sub64 64-bit and 32-bit
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * Here are some amendments which address 64-bit vs. 32-bit portability issues.
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * Some facts first:
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * - On 64-bit Windows the type long remains 32-bit. On nearly all other
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * 64-bit platforms long is 64-bit.
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * - On all 64-bit platforms we care about, int is 32-bit, short is 16 bit
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * and char is 8-bit.
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * (I don't know about any platforms yet where this isn't true.)
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * - size_t, ssize_t, uintptr_t, ptrdiff_t and similar are all 64-bit on
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * 64-bit platforms. (These are 32-bit on 32-bit platforms.)
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * - There is no inline assembly support in the 64-bit Microsoft compilers.
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * Now for the guidelines:
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * - Never, ever, use int, long, ULONG, LONG, DWORD or similar to cast a
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * pointer to integer. Use uintptr_t or intptr_t. If you have to use
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * NT/Windows types, there is the choice of ULONG_PTR and DWORD_PTR.
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * - RT_OS_WINDOWS is defined to indicate Windows. Do not use __WIN32__,
a8a5fcde141c804932506d0c09088bfe66a9f111vboxsync * __WIN64__ and __WIN__ because they are all deprecated and scheduled
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * for removal (if not removed already). Do not use the compiler
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * defined _WIN32, _WIN64, or similar either. The bitness can be
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * determined by testing ARCH_BITS.
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * #ifdef RT_OS_WINDOWS
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * // call win32/64 api.
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * #ifdef RT_OS_WINDOWS
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * # if ARCH_BITS == 64
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * // call win64 api.
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * # else // ARCH_BITS == 32
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * // call win32 api.
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * # endif // ARCH_BITS == 32
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * #else // !RT_OS_WINDOWS
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * // call posix api
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * #endif // !RT_OS_WINDOWS
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * - There are RT_OS_xxx defines for each OS, just like RT_OS_WINDOWS
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * mentioned above. Use these defines instead of any predefined
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * compiler stuff or defines from system headers.
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * - RT_ARCH_X86 is defined when compiling for the x86 the architecture.
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * Do not use __x86__, __X86__, __[Ii]386__, __[Ii]586__, or similar
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * for this purpose.
a8a5fcde141c804932506d0c09088bfe66a9f111vboxsync * - RT_ARCH_AMD64 is defined when compiling for the AMD64 architecture.
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * Do not use __AMD64__, __amd64__ or __x64_86__.
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * - Take care and use size_t when you have to, esp. when passing a pointer
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * to a size_t as a parameter.
b100028fe14f5158e2f6fb47b4473c0b0dfd7234vboxsync * - Be wary of type promotion to (signed) integer. For example the
b100028fe14f5158e2f6fb47b4473c0b0dfd7234vboxsync * following will cause u8 to be promoted to int in the shift, and then
b100028fe14f5158e2f6fb47b4473c0b0dfd7234vboxsync * sign extended in the assignment 64-bit:
b100028fe14f5158e2f6fb47b4473c0b0dfd7234vboxsync * uint8_t u8 = 0xfe;
b100028fe14f5158e2f6fb47b4473c0b0dfd7234vboxsync * uint64_t u64 = u8 << 24;
b100028fe14f5158e2f6fb47b4473c0b0dfd7234vboxsync * // u64 == 0xfffffffffe000000
6add97a7b2999559af482d032116fe1d78f33ec0vboxsync * @subsection sec_vbox_guideline_compulsory_cppmain C++ guidelines for Main
6add97a7b2999559af482d032116fe1d78f33ec0vboxsync * Main is currently (2009) full of hard-to-maintain code that uses complicated
6add97a7b2999559af482d032116fe1d78f33ec0vboxsync * templates. The new mid-term goal for Main is to have less custom templates
6add97a7b2999559af482d032116fe1d78f33ec0vboxsync * instead of more for the following reasons:
6add97a7b2999559af482d032116fe1d78f33ec0vboxsync * - Template code is harder to read and understand. Custom templates create
6add97a7b2999559af482d032116fe1d78f33ec0vboxsync * territories which only the code writer understands.
6add97a7b2999559af482d032116fe1d78f33ec0vboxsync * - Errors in using templates create terrible C++ compiler messages.
6add97a7b2999559af482d032116fe1d78f33ec0vboxsync * - Template code is really hard to look at in a debugger.
6add97a7b2999559af482d032116fe1d78f33ec0vboxsync * - Templates slow down the compiler a lot.
6add97a7b2999559af482d032116fe1d78f33ec0vboxsync * In particular, the following bits should be considered deprecated and should
6add97a7b2999559af482d032116fe1d78f33ec0vboxsync * NOT be used in new code:
6add97a7b2999559af482d032116fe1d78f33ec0vboxsync * - everything in include/iprt/cpputils.h (auto_ref_ptr, exception_trap_base,
6add97a7b2999559af482d032116fe1d78f33ec0vboxsync * char_auto_ptr and friends)
6add97a7b2999559af482d032116fe1d78f33ec0vboxsync * Generally, in many cases, a simple class with a proper destructor can achieve
6add97a7b2999559af482d032116fe1d78f33ec0vboxsync * the same effect as a 1,000-line template include file, and the code is
6add97a7b2999559af482d032116fe1d78f33ec0vboxsync * much more accessible that way.
6add97a7b2999559af482d032116fe1d78f33ec0vboxsync * Using standard STL templates like std::list, std::vector and std::map is OK.
6add97a7b2999559af482d032116fe1d78f33ec0vboxsync * Exceptions are:
6add97a7b2999559af482d032116fe1d78f33ec0vboxsync * - Guest Additions because we don't want to link against libstdc++ there.
6add97a7b2999559af482d032116fe1d78f33ec0vboxsync * - std::string should not be used because we have iprt::MiniString and
6add97a7b2999559af482d032116fe1d78f33ec0vboxsync * com::Utf8Str which can convert efficiently with COM's UTF-16 strings.
6add97a7b2999559af482d032116fe1d78f33ec0vboxsync * - std::auto_ptr<> in general; that part of the C++ standard is just broken.
6add97a7b2999559af482d032116fe1d78f33ec0vboxsync * Write a destructor that calls delete.
857dbac5b1cb353bf11b4b335443f51e63c4d29fvboxsync * @subsection sec_vbox_guideline_compulsory_cppqtgui C++ guidelines for the Qt GUI
857dbac5b1cb353bf11b4b335443f51e63c4d29fvboxsync * The Qt GUI is currently (2010) on its way to become more compatible to the
857dbac5b1cb353bf11b4b335443f51e63c4d29fvboxsync * rest of VirtualBox coding style wise. From now on, all the coding style
857dbac5b1cb353bf11b4b335443f51e63c4d29fvboxsync * rules described in this file are also mandatory for the Qt GUI. Additionally
857dbac5b1cb353bf11b4b335443f51e63c4d29fvboxsync * the following rules should be respected:
857dbac5b1cb353bf11b4b335443f51e63c4d29fvboxsync * - GUI classes which correspond to GUI tasks should be prefixed by UI (no VBox anymore)
857dbac5b1cb353bf11b4b335443f51e63c4d29fvboxsync * - Classes which extents some of the Qt classes should be prefix by QI
857dbac5b1cb353bf11b4b335443f51e63c4d29fvboxsync * - General task classes should be prefixed by C
857dbac5b1cb353bf11b4b335443f51e63c4d29fvboxsync * - Slots are prefixed by slt -> sltName
857dbac5b1cb353bf11b4b335443f51e63c4d29fvboxsync * - Signals are prefixed by sig -> sigName
857dbac5b1cb353bf11b4b335443f51e63c4d29fvboxsync * - Use Qt classes for lists, strings and so on, the use of STL classes should
857dbac5b1cb353bf11b4b335443f51e63c4d29fvboxsync * be avoided
857dbac5b1cb353bf11b4b335443f51e63c4d29fvboxsync * - All files like .cpp, .h, .ui, which belong together are located in the
857dbac5b1cb353bf11b4b335443f51e63c4d29fvboxsync * same directory and named the same
b196cd75895b6a2a67b83131859eefebbaf04df6vboxsync * @subsection sec_vbox_guideline_compulsory_xslt XSLT
b196cd75895b6a2a67b83131859eefebbaf04df6vboxsync * XSLT (eXtensible Stylesheet Language Transformations) is used quite a bit in
b196cd75895b6a2a67b83131859eefebbaf04df6vboxsync * the Main API area of VirtualBox to generate sources and bindings to that API.
b196cd75895b6a2a67b83131859eefebbaf04df6vboxsync * There are a couple of common pitfalls worth mentioning:
b196cd75895b6a2a67b83131859eefebbaf04df6vboxsync * - Never do repeated //interface[@name=...] and //enum[@name=...] lookups
b196cd75895b6a2a67b83131859eefebbaf04df6vboxsync * because they are expensive. Instead delcare xsl:key elements for these
b196cd75895b6a2a67b83131859eefebbaf04df6vboxsync * searches and do the lookup using the key() function. xsltproc uses
b196cd75895b6a2a67b83131859eefebbaf04df6vboxsync * (per current document) hash tables for each xsl:key, i.e. very fast.
b196cd75895b6a2a67b83131859eefebbaf04df6vboxsync * - When output type is 'text' make sure to call xsltprocNewlineOutputHack
b196cd75895b6a2a67b83131859eefebbaf04df6vboxsync * from typemap-shared.inc.xsl every few KB of output, or xsltproc will
b196cd75895b6a2a67b83131859eefebbaf04df6vboxsync * end up wasting all the time reallocating the output buffer.
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * @section sec_vbox_guideline_optional Optional
cc9afa50617a487414e35811204aa80bf06c565cvboxsync * First part is the actual coding style and all the prefixes. The second part
a8a5fcde141c804932506d0c09088bfe66a9f111vboxsync * is a bunch of good advice.
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * @subsection sec_vbox_guideline_optional_layout The code layout
cc9afa50617a487414e35811204aa80bf06c565cvboxsync * - Max line length is 130 chars. Exceptions are table-like
cc9afa50617a487414e35811204aa80bf06c565cvboxsync * code/initializers and Log*() statements (don't waste unnecessary
cc9afa50617a487414e35811204aa80bf06c565cvboxsync * vertical space on debug logging).
6871f6e668eff418859534066dcb011946f52289vboxsync * - Comments should try stay within the usual 80 columns as these are
6871f6e668eff418859534066dcb011946f52289vboxsync * denser and too long lines may be harder to read.
cc9afa50617a487414e35811204aa80bf06c565cvboxsync * - Curly brackets are not indented. Example:
cc9afa50617a487414e35811204aa80bf06c565cvboxsync * if (true)
cc9afa50617a487414e35811204aa80bf06c565cvboxsync * Something1();
cc9afa50617a487414e35811204aa80bf06c565cvboxsync * Something2();
cc9afa50617a487414e35811204aa80bf06c565cvboxsync * SomethingElse1().
cc9afa50617a487414e35811204aa80bf06c565cvboxsync * SomethingElse2().
cc9afa50617a487414e35811204aa80bf06c565cvboxsync * - Space before the parentheses when it comes after a C keyword.
cc9afa50617a487414e35811204aa80bf06c565cvboxsync * - No space between argument and parentheses. Exception for complex
cc9afa50617a487414e35811204aa80bf06c565cvboxsync * expression. Example:
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * if (PATMR3IsPatchGCAddr(pVM, GCPtr))
a8a5fcde141c804932506d0c09088bfe66a9f111vboxsync * - The else of an if is always the first statement on a line. (No curly
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * stuff before it!)
a8a5fcde141c804932506d0c09088bfe66a9f111vboxsync * - else and if go on the same line if no { compound statement }
cc9afa50617a487414e35811204aa80bf06c565cvboxsync * follows the if. Example:
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * if (fFlags & MYFLAGS_1)
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * fFlags &= ~MYFLAGS_10;
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * else if (fFlags & MYFLAGS_2)
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * fFlags &= ~MYFLAGS_MASK;
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * fFlags |= MYFLAGS_5;
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * else if (fFlags & MYFLAGS_3)
cc9afa50617a487414e35811204aa80bf06c565cvboxsync * - Slightly complex boolean expressions are split into multiple lines,
cc9afa50617a487414e35811204aa80bf06c565cvboxsync * putting the operators first on the line and indenting it all according
cc9afa50617a487414e35811204aa80bf06c565cvboxsync * to the nesting of the expression. The purpose is to make it as easy as
cc9afa50617a487414e35811204aa80bf06c565cvboxsync * possible to read. Example:
cc9afa50617a487414e35811204aa80bf06c565cvboxsync * if ( RT_SUCCESS(rc)
cc9afa50617a487414e35811204aa80bf06c565cvboxsync * || (fFlags & SOME_FLAG))
cc9afa50617a487414e35811204aa80bf06c565cvboxsync * - When 'if' or 'while' statements gets long, the closing parentheses
cc9afa50617a487414e35811204aa80bf06c565cvboxsync * goes right below the opening parentheses. This may be applied to
cc9afa50617a487414e35811204aa80bf06c565cvboxsync * sub-expression. Example:
cc9afa50617a487414e35811204aa80bf06c565cvboxsync * if ( RT_SUCCESS(rc)
cc9afa50617a487414e35811204aa80bf06c565cvboxsync * || ( fSomeStuff
cc9afa50617a487414e35811204aa80bf06c565cvboxsync * && fSomeOtherStuff
cc9afa50617a487414e35811204aa80bf06c565cvboxsync * && fEvenMoreStuff
cc9afa50617a487414e35811204aa80bf06c565cvboxsync * || SomePredicateFunction()
cc9afa50617a487414e35811204aa80bf06c565cvboxsync * - The case is indented from the switch (to avoid having the braces for
cc9afa50617a487414e35811204aa80bf06c565cvboxsync * the 'case' at the same level as the 'switch' statement).
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * - If a case needs curly brackets they contain the entire case, are not
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * indented from the case, and the break or return is placed inside them.
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * switch (pCur->eType)
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * case PGMMAPPINGTYPE_PAGETABLES:
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * unsigned iPDE = pCur->GCPtr >> PGDIR_SHIFT;
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * unsigned iPT = (pCur->GCPtrEnd - pCur->GCPtr) >> PGDIR_SHIFT;
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * while (iPT-- > 0)
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * if (pPD->a[iPDE + iPT].n.u1Present)
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * return VERR_HYPERVISOR_CONFLICT;
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * - In a do while construction, the while is on the same line as the
a8a5fcde141c804932506d0c09088bfe66a9f111vboxsync * closing "}" if any are used.
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * } while (i > 0);
cc9afa50617a487414e35811204aa80bf06c565cvboxsync * - Comments are in C style. C++ style comments are used for temporary
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * disabling a few lines of code.
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * - No unnecessary parentheses in expressions (just don't over do this
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * so that gcc / msc starts bitching). Find a correct C/C++ operator
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * precedence table if needed.
cc9afa50617a487414e35811204aa80bf06c565cvboxsync * - 'for (;;)' is preferred over 'while (true)' and 'while (1)'.
cc9afa50617a487414e35811204aa80bf06c565cvboxsync * - Parameters are indented to the start parentheses when breaking up
cc9afa50617a487414e35811204aa80bf06c565cvboxsync * function calls, declarations or prototypes. (This is in line with
cc9afa50617a487414e35811204aa80bf06c565cvboxsync * how 'if', 'for' and 'while' statements are done as well.) Example:
cc9afa50617a487414e35811204aa80bf06c565cvboxsync * RTPROCESS hProcess;
cc9afa50617a487414e35811204aa80bf06c565cvboxsync * int rc = RTProcCreateEx(papszArgs[0],
cc9afa50617a487414e35811204aa80bf06c565cvboxsync * papszArgs,
cc9afa50617a487414e35811204aa80bf06c565cvboxsync * RTENV_DEFAULT,
cc9afa50617a487414e35811204aa80bf06c565cvboxsync * NULL, // phStdIn
cc9afa50617a487414e35811204aa80bf06c565cvboxsync * NULL, // phStdOut
cc9afa50617a487414e35811204aa80bf06c565cvboxsync * NULL, // phStdErr
cc9afa50617a487414e35811204aa80bf06c565cvboxsync * NULL, // pszAsUser
cc9afa50617a487414e35811204aa80bf06c565cvboxsync * NULL, // pszPassword
cc9afa50617a487414e35811204aa80bf06c565cvboxsync * &hProcess);
cc9afa50617a487414e35811204aa80bf06c565cvboxsync * - That Dijkstra is dead is no excuse for using gotos.
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * @subsection sec_vbox_guideline_optional_prefix Variable / Member Prefixes
6871f6e668eff418859534066dcb011946f52289vboxsync * Prefixes are meant to provide extra context clues to a variable/member, we
6871f6e668eff418859534066dcb011946f52289vboxsync * therefore avoid using prefixes that just indicating the type if a better
6871f6e668eff418859534066dcb011946f52289vboxsync * choice is available.
6871f6e668eff418859534066dcb011946f52289vboxsync * The prefixes:
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * - The 'g_' (or 'g') prefix means a global variable, either on file or module level.
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * - The 's_' (or 's') prefix means a static variable inside a function or class.
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * - The 'm_' (or 'm') prefix means a class data member.
cc9afa50617a487414e35811204aa80bf06c565cvboxsync * In new code in Main, use "m_" (and common sense). As an exception,
cc9afa50617a487414e35811204aa80bf06c565cvboxsync * in Main, if a class encapsulates its member variables in an anonymous
f78b46ef35ec753172597d7ebdb6845b4a640582vboxsync * structure which is declared in the class, but defined only in the
cc9afa50617a487414e35811204aa80bf06c565cvboxsync * implementation (like this: 'class X { struct Data; Data *m; }'), then
cc9afa50617a487414e35811204aa80bf06c565cvboxsync * the pointer to that struct is called 'm' itself and its members then
cc9afa50617a487414e35811204aa80bf06c565cvboxsync * need no prefix, because the members are accessed with 'm->member'
cc9afa50617a487414e35811204aa80bf06c565cvboxsync * already which is clear enough.
cc9afa50617a487414e35811204aa80bf06c565cvboxsync * - The 'a_' prefix means a parameter (argument) variable. This is
cc9afa50617a487414e35811204aa80bf06c565cvboxsync * sometimes written 'a' in parts of the source code that does not use
cc9afa50617a487414e35811204aa80bf06c565cvboxsync * the array prefix.
cc9afa50617a487414e35811204aa80bf06c565cvboxsync * - The 'p' prefix means pointer. For instance 'pVM' is pointer to VM.
cc9afa50617a487414e35811204aa80bf06c565cvboxsync * - The 'r' prefix means that something is passed by reference.
cc9afa50617a487414e35811204aa80bf06c565cvboxsync * - The 'k' prefix means that something is a constant. For instance
cc9afa50617a487414e35811204aa80bf06c565cvboxsync * 'enum { kStuff };'. This is usually not used in combination with
cc9afa50617a487414e35811204aa80bf06c565cvboxsync * 'p', 'r' or any such thing, it's main main use is to make enums
cc9afa50617a487414e35811204aa80bf06c565cvboxsync * easily identifiable.
cc9afa50617a487414e35811204aa80bf06c565cvboxsync * - The 'a' prefix means array. For instance 'aPages' could be read as
cc9afa50617a487414e35811204aa80bf06c565cvboxsync * array of pages.
cc9afa50617a487414e35811204aa80bf06c565cvboxsync * - The 'c' prefix means count. For instance 'cbBlock' could be read,
cc9afa50617a487414e35811204aa80bf06c565cvboxsync * count of bytes in block.
6871f6e668eff418859534066dcb011946f52289vboxsync * - The 'cx' prefix means width (count of 'x' units).
6871f6e668eff418859534066dcb011946f52289vboxsync * - The 'cy' prefix means height (count of 'y' units).
6871f6e668eff418859534066dcb011946f52289vboxsync * - The 'x', 'y' and 'z' prefix refers to the x-, y- , and z-axis
6871f6e668eff418859534066dcb011946f52289vboxsync * respectively.
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * - The 'off' prefix means offset.
cc9afa50617a487414e35811204aa80bf06c565cvboxsync * - The 'i' or 'idx' prefixes usually means index. Although the 'i' one
cc9afa50617a487414e35811204aa80bf06c565cvboxsync * can sometimes just mean signed integer.
cc9afa50617a487414e35811204aa80bf06c565cvboxsync * - The 'i[1-9]+' prefix means a fixed bit size variable. Frequently
6871f6e668eff418859534066dcb011946f52289vboxsync * used with the int[1-9]+_t types where the width is really important.
6871f6e668eff418859534066dcb011946f52289vboxsync * In most cases 'i' is more appropriate. [type]
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * - The 'e' (or 'enm') prefix means enum.
cc9afa50617a487414e35811204aa80bf06c565cvboxsync * - The 'u' prefix usually means unsigned integer. Exceptions follows.
cc9afa50617a487414e35811204aa80bf06c565cvboxsync * - The 'u[1-9]+' prefix means a fixed bit size variable. Frequently
6871f6e668eff418859534066dcb011946f52289vboxsync * used with the uint[1-9]+_t types and with bitfields where the width is
6871f6e668eff418859534066dcb011946f52289vboxsync * really important. In most cases 'u' or 'b' (byte) would be more
6871f6e668eff418859534066dcb011946f52289vboxsync * appropriate. [type]
cc9afa50617a487414e35811204aa80bf06c565cvboxsync * - The 'b' prefix means byte or bytes. [type]
cc9afa50617a487414e35811204aa80bf06c565cvboxsync * - The 'f' prefix means flags. Flags are unsigned integers of some kind
cc9afa50617a487414e35811204aa80bf06c565cvboxsync * or booleans.
cc9afa50617a487414e35811204aa80bf06c565cvboxsync * - TODO: need prefix for real float. [type]
cc9afa50617a487414e35811204aa80bf06c565cvboxsync * - The 'rd' prefix means real double and is used for 'double' variables.
cc9afa50617a487414e35811204aa80bf06c565cvboxsync * - The 'lrd' prefix means long real double and is used for 'long double'
cc9afa50617a487414e35811204aa80bf06c565cvboxsync * variables. [type]
cc9afa50617a487414e35811204aa80bf06c565cvboxsync * - The 'ch' prefix means a char, the (signed) char type. [type]
cc9afa50617a487414e35811204aa80bf06c565cvboxsync * - The 'wc' prefix means a wide/windows char, the RTUTF16 type. [type]
cc9afa50617a487414e35811204aa80bf06c565cvboxsync * - The 'uc' prefix means a Unicode Code point, the RTUNICP type. [type]
cc9afa50617a487414e35811204aa80bf06c565cvboxsync * - The 'uch' prefix means unsigned char. It's rarely used. [type]
cc9afa50617a487414e35811204aa80bf06c565cvboxsync * - The 'sz' prefix means zero terminated character string (array of
cc9afa50617a487414e35811204aa80bf06c565cvboxsync * chars). (UTF-8)
cc9afa50617a487414e35811204aa80bf06c565cvboxsync * - The 'wsz' prefix means zero terminated wide/windows character string
cc9afa50617a487414e35811204aa80bf06c565cvboxsync * (array of RTUTF16).
cc9afa50617a487414e35811204aa80bf06c565cvboxsync * - The 'usz' prefix means zero terminated Unicode string (array of
cc9afa50617a487414e35811204aa80bf06c565cvboxsync * RTUNICP).
857dbac5b1cb353bf11b4b335443f51e63c4d29fvboxsync * - The 'str' prefix means C++ string; either a std::string or, in Main,
cc9afa50617a487414e35811204aa80bf06c565cvboxsync * a Utf8Str or, in Qt, a QString. When used with 'p', 'r', 'a' or 'c'
cc9afa50617a487414e35811204aa80bf06c565cvboxsync * the first letter should be capitalized.
cc9afa50617a487414e35811204aa80bf06c565cvboxsync * - The 'bstr' prefix, in Main, means a UTF-16 Bstr. When used with 'p',
cc9afa50617a487414e35811204aa80bf06c565cvboxsync * 'r', 'a' or 'c' the first letter should be capitalized.
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * - The 'pfn' prefix means pointer to function. Common usage is 'pfnCallback'
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * and such like.
cc9afa50617a487414e35811204aa80bf06c565cvboxsync * - The 'psz' prefix is a combination of 'p' and 'sz' and thus means
cc9afa50617a487414e35811204aa80bf06c565cvboxsync * pointer to a zero terminated character string. (UTF-8)
cc9afa50617a487414e35811204aa80bf06c565cvboxsync * - The 'pcsz' prefix is used to indicate constant string pointers in
cc9afa50617a487414e35811204aa80bf06c565cvboxsync * parts of the code. Most code uses 'psz' for const and non-const
cc9afa50617a487414e35811204aa80bf06c565cvboxsync * string pointers.
cc9afa50617a487414e35811204aa80bf06c565cvboxsync * - The 'l' prefix means (signed) long. We try avoid using this,
cc9afa50617a487414e35811204aa80bf06c565cvboxsync * expecially with the 'LONG' types in Main as these are not 'long' on
cc9afa50617a487414e35811204aa80bf06c565cvboxsync * 64-bit non-Windows platforms and can cause confusion. Alternatives:
cc9afa50617a487414e35811204aa80bf06c565cvboxsync * 'i' or 'i32'. [type]
cc9afa50617a487414e35811204aa80bf06c565cvboxsync * - The 'ul' prefix means unsigned long. We try avoid using this,
cc9afa50617a487414e35811204aa80bf06c565cvboxsync * expecially with the 'ULONG' types in Main as these are not 'unsigned
cc9afa50617a487414e35811204aa80bf06c565cvboxsync * long' on 64-bit non-Windows platforms and can cause confusion.
cc9afa50617a487414e35811204aa80bf06c565cvboxsync * Alternatives: 'u' or 'u32'. [type]
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * @subsection sec_vbox_guideline_optional_misc Misc / Advice / Stuff
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * - When writing code think as the reader.
0c79da3f59c9408efed6560a7b64bf1aca3fc19dvboxsync * - When writing code think as the compiler. (2)
a8a5fcde141c804932506d0c09088bfe66a9f111vboxsync * - When reading code think as if it's full of bugs - find them and fix them.
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * - Pointer within range tests like:
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * if ((uintptr_t)pv >= (uintptr_t)pvBase && (uintptr_t)pv < (uintptr_t)pvBase + cbRange)
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * Can also be written as (assuming cbRange unsigned):
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * if ((uintptr_t)pv - (uintptr_t)pvBase < cbRange)
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * Which is shorter and potentially faster. (1)
a8a5fcde141c804932506d0c09088bfe66a9f111vboxsync * - Avoid unnecessary casting. All pointers automatically cast down to
a8a5fcde141c804932506d0c09088bfe66a9f111vboxsync * void *, at least for non class instance pointers.
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * - It's very very bad practise to write a function larger than a
a8a5fcde141c804932506d0c09088bfe66a9f111vboxsync * screen full (1024x768) without any comprehensibility and explaining
a8a5fcde141c804932506d0c09088bfe66a9f111vboxsync * comments.
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * - More to come....
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * (1) Important, be very careful with the casting. In particular, note that
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * a compiler might treat pointers as signed (IIRC).
0c79da3f59c9408efed6560a7b64bf1aca3fc19dvboxsync * (2) "A really advanced hacker comes to understand the true inner workings of
0c79da3f59c9408efed6560a7b64bf1aca3fc19dvboxsync * the machine - he sees through the language he's working in and glimpses
0c79da3f59c9408efed6560a7b64bf1aca3fc19dvboxsync * the secret functioning of the binary code - becomes a Ba'al Shem of
0c79da3f59c9408efed6560a7b64bf1aca3fc19dvboxsync * sorts." (Neal Stephenson "Snow Crash")
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * @section sec_vbox_guideline_warnings Compiler Warnings
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * The code should when possible compile on all platforms and compilers without any
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * warnings. That's a nice idea, however, if it means making the code harder to read,
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * less portable, unreliable or similar, the warning should not be fixed.
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * Some of the warnings can seem kind of innocent at first glance. So, let's take the
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * most common ones and explain them.
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * @subsection sec_vbox_guideline_warnings_signed_unsigned_compare Signed / Unsigned Compare
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * GCC says: "warning: comparison between signed and unsigned integer expressions"
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * MSC says: "warning C4018: '<|<=|==|>=|>' : signed/unsigned mismatch"
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * The following example will not output what you expect:
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync signed long a = -1;
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync unsigned long b = 2294967295;
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync printf("%ld < %lu: true\n", a, b);
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync printf("%ld < %lu: false\n", a, b);
a8a5fcde141c804932506d0c09088bfe66a9f111vboxsync * If I understood it correctly, the compiler will convert a to an
a8a5fcde141c804932506d0c09088bfe66a9f111vboxsync * unsigned long before doing the compare.
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * @section sec_vbox_guideline_svn Subversion Commit Rules
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * Before checking in:
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * - Check Tinderbox and make sure the tree is green across all platforms. If it's
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * red on a platform, don't check in. If you want, warn in the \#vbox channel and
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * help make the responsible person fix it.
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * NEVER CHECK IN TO A BROKEN BUILD.
a8a5fcde141c804932506d0c09088bfe66a9f111vboxsync * - When checking in keep in mind that a commit is atomic and that the Tinderbox and
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * developers are constantly checking out the tree. Therefore do not split up the
a8a5fcde141c804932506d0c09088bfe66a9f111vboxsync * commit unless it's into 100% independent parts. If you need to split it up in order
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * to have sensible commit comments, make the sub-commits as rapid as possible.
a8a5fcde141c804932506d0c09088bfe66a9f111vboxsync * - If you make a user visible change, such as fixing a reported bug,
a8a5fcde141c804932506d0c09088bfe66a9f111vboxsync * make sure you add an entry to doc/manual/user_ChangeLogImpl.xml.
6829fa7e057359ac605f0b391676bfa338a8b818vboxsync * - If you are adding files make sure set the right attributes.
6829fa7e057359ac605f0b391676bfa338a8b818vboxsync * svn-ps.sh/cmd was created for this purpose, please make use of it.
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * After checking in:
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * - After checking-in, you watch Tinderbox until your check-ins clear. You do not
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * go home. You do not sleep. You do not log out or experiment with drugs. You do
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * not become unavailable. If you break the tree, add a comment saying that you're
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * fixing it. If you can't fix it and need help, ask in the \#innotek channel or back
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * out the change.
173a5488291528af464ae4bc4f2e4a0c7a139c49vboxsync * (Inspired by mozilla tree rules.)