VirtualBox

Changeset 30954 in vbox


Ignore:
Timestamp:
Jul 21, 2010 12:37:49 PM (14 years ago)
Author:
vboxsync
Message:

doc/VBox-CodingGuidelines.cpp: Added bits that was asked for on the mailing list as well as documenting some prefixes we're using.

File:
1 edited

Legend:

Unmodified
Added
Removed

  • trunk/doc/VBox-CodingGuidelines.cpp

    r28800 r30954  
    2929 * @section sec_vbox_guideline_compulsory       Compulsory
    3030 *
     31 *
     32 *      - The indentation size is 4 chars.
     33 *
     34 *      - Tabs are only ever used in makefiles.
    3135 *
    3236 *      - Use RT and VBOX types.
    … …  
    258262 * @section sec_vbox_guideline_optional         Optional
    259263 *
    260  * First part is the actual coding style and all the prefixes. The second part
     264 * First part is the actual coding style and all the prefixes.  The second part
    261265 * is a bunch of good advice.
    262266 *
    … …  
    264268 * @subsection sec_vbox_guideline_optional_layout   The code layout
    265269 *
    266  *      - Curly brackets are not indented.
    267  *
    268  *      - Space before the parenthesis when it comes after a C keyword.
    269  *
    270  *      - No space between argument and parenthesis. Exception for complex
    271  *        expression.
    272  *        Example:
     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).
     273 *
     274 *      - Comments should try stay within the usual 80 columns.
     275 *
     276 *      - Curly brackets are not indented.  Example:
     277 *        @code
     278 *              if (true)
     279 *              {
     280 *                  Something1();
     281 *                  Something2();
     282 *              }
     283 *              else
     284 *              {
     285 *                  SomethingElse1().
     286 *                  SomethingElse2().
     287 *              }
     288 *        @endcode
     289 *
     290 *      - Space before the parentheses when it comes after a C keyword.
     291 *
     292 *      - No space between argument and parentheses. Exception for complex
     293 *        expression.  Example:
    273294 *        @code
    274295 *              if (PATMR3IsPatchGCAddr(pVM, GCPtr))
    … …  
    279300 *
    280301 *      - else and if go on the same line if no { compound statement }
    281  *        follows the if.
    282  *        Example:
     302 *        follows the if.  Example:
    283303 *        @code
    284304 *              if (fFlags & MYFLAGS_1)
    … …  
    292312 *        @endcode
    293313 *
    294  *      - The case is indented from the switch.
     314 *
     315 *      - Slightly complex boolean expressions are split into multiple lines,
     316 *        putting the operators first on the line and indenting it all according
     317 *        to the nesting of the expression. The purpose is to make it as easy as
     318 *        possible to read.  Example:
     319 *        @code
     320 *              if (    RT_SUCCESS(rc)
     321 *                  ||  (fFlags & SOME_FLAG))
     322 *        @endcode
     323 *
     324 *      - When 'if' or  'while' statements gets long, the closing parentheses
     325 *        goes right below the opening parentheses.  This may be applied to
     326 *        sub-expression.  Example:
     327 *        @code
     328 *              if (    RT_SUCCESS(rc)
     329 *                  ||  (   fSomeStuff
     330 *                       && fSomeOtherStuff
     331 *                       && fEvenMoreStuff
     332 *                      )
     333 *                  ||  SomePredicateFunction()
     334 *                 )
     335 *              {
     336 *                  ...
     337 *              }
     338 *        @endcode
     339 *
     340 *      - The case is indented from the switch (to avoid having the braces for
     341 *        the 'case' at the same level as the 'switch' statement).
    295342 *
    296343 *      - If a case needs curly brackets they contain the entire case, are not
    … …  
    323370 *        @endcode
    324371 *
    325  *      - Comments are in C style. C++ style comments are used for temporary
     372 *      - Comments are in C style.  C++ style comments are used for temporary
    326373 *        disabling a few lines of code.
    327  *
    328  *      - Slightly complex boolean expressions are split into multiple lines,
    329  *        putting the operators first on the line and indenting it all according
    330  *        to the nesting of the expression. The purpose is to make it as easy as
    331  *        possible to read.
    332  *        Example:
    333  *        @code
    334  *              if (    RT_SUCCESS(rc)
    335  *                  ||  (fFlags & SOME_FLAG))
    336  *        @endcode
    337374 *
    338375 *      - No unnecessary parentheses in expressions (just don't over do this
    … …  
    340377 *        precedence table if needed.
    341378 *
     379 *      - 'for (;;)' is preferred over 'while (true)' and 'while (1)'.
     380 *
     381 *      - Parameters are indented to the start parentheses when breaking up
     382 *        function calls, declarations or prototypes.  (This is in line with
     383 *        how 'if', 'for' and 'while' statements are done as well.) Example:
     384 *        @code
     385 *              RTPROCESS hProcess;
     386 *              int rc = RTProcCreateEx(papszArgs[0],
     387 *                                      papszArgs,
     388 *                                      RTENV_DEFAULT,
     389 *                                      fFlags,
     390 *                                      NULL,           // phStdIn
     391 *                                      NULL,           // phStdOut
     392 *                                      NULL,           // phStdErr
     393 *                                      NULL,           // pszAsUser
     394 *                                      NULL,           // pszPassword
     395 *                                      &hProcess);
     396 *        @endcode
     397 *
     398 *      - That Dijkstra is dead is no excuse for using gotos.
     399 *
     400 *
    342401 *
    343402 * @subsection sec_vbox_guideline_optional_prefix   Variable / Member Prefixes
    … …  
    349408 *      - The 'm_' (or 'm') prefix means a class data member.
    350409 *
    351  *        In new code in Main, use "m_" (and common sense). As an exception, in Main,
    352  *        if a class encapsulates its member variables in an anonymous
     410 *        In new code in Main, use "m_" (and common sense).  As an exception,
     411 *        in Main, if a class encapsulates its member variables in an anonymous
    353412 *        structure which is declared in the class, but defined only in the
    354  *        implementation (like this: "class X { struct Data; Data *m; }"), then
    355  *        the pointer to that struct is called "m" itself and its members then need no prefix,
    356  *        because the members are accessed with "m->member" already which is clear enough.
    357  *
    358  *      - The 'p' prefix means pointer. For instance 'pVM' is pointer to VM.
    359  *
    360  *      - The 'a' prefix means array. For instance 'aPages' could be read as array
    361  *        of pages.
    362  *
    363  *      - The 'c' prefix means count. For instance 'cbBlock' could be read, count
    364  *        of bytes in block.
     413 *        implementation (like this: 'class X { struct Data; Data *m; }'), then
     414 *        the pointer to that struct is called 'm' itself and its members then
     415 *        need no prefix, because the members are accessed with 'm->member'
     416 *        already which is clear enough.
     417 *
     418 *      - The 'a_' prefix means a parameter (argument) variable.  This is
     419 *        sometimes written 'a' in parts of the source code that does not use
     420 *        the array prefix.
     421 *
     422 *      - The 'p' prefix means pointer.  For instance 'pVM' is pointer to VM.
     423 *
     424 *      - The 'r' prefix means that something is passed by reference.
     425 *
     426 *      - The 'k' prefix means that something is a constant.  For instance
     427 *        'enum { kStuff };'.  This is usually not used in combination with
     428 *        'p', 'r' or any such thing, it's main main use is to make enums
     429 *        easily identifiable.
     430 *
     431 *      - The 'a' prefix means array.  For instance 'aPages' could be read as
     432 *        array of pages.
     433 *
     434 *      - The 'c' prefix means count.  For instance 'cbBlock' could be read,
     435 *        count of bytes in block.
    365436 *
    366437 *      - The 'off' prefix means offset.
    367438 *
    368  *      - The 'i' or 'idx' prefixes usually means index. Although the 'i' one can
    369  *        sometimes just mean signed integer.
     439 *      - The 'i' or 'idx' prefixes usually means index.  Although the 'i' one
     440 *        can sometimes just mean signed integer.
     441 *
     442 *      - The 'i[1-9]+' prefix means a fixed bit size variable.  Frequently
     443 *        used with the int[1-9]+_t types.  [type]
    370444 *
    371445 *      - The 'e' (or 'enm') prefix means enum.
    372446 *
    373  *      - The 'u' prefix usually means unsigned integer. Exceptions follows.
    374  *
    375  *      - The 'u[1-9]+' prefix means a fixed bit size variable. Frequently used
    376  *        with the uint[1-9]+_t types and with bitfields.
    377  *
    378  *      - The 'b' prefix means byte or bytes.
    379  *
    380  *      - The 'f' prefix means flags. Flags are unsigned integers of some kind or bools.
    381  *
    382  *      - The 'ch' prefix means a char, the (signed) char type.
    383  *
    384  *      - The 'wc' prefix means a wide/windows char, the RTUTF16 type.
    385  *
    386  *      - The 'uc' prefix means a Unicode Code point, the RTUNICP type.
    387  *
    388  *      - The 'uch' prefix means unsigned char. It's rarely used.
    389  *
    390  *      - The 'sz' prefix means zero terminated character string (array of chars). (UTF-8)
    391  *
    392  *      - The 'wsz' prefix means zero terminated wide/windows character string (array of RTUTF16).
    393  *
    394  *      - The 'usz' prefix means zero terminated Unicode string (array of RTUNICP).
     447 *      - The 'u' prefix usually means unsigned integer.  Exceptions follows.
     448 *
     449 *      - The 'u[1-9]+' prefix means a fixed bit size variable.  Frequently
     450 *        used with the uint[1-9]+_t types and with bitfields.  [type]
     451 *
     452 *      - The 'b' prefix means byte or bytes.  [type]
     453 *
     454 *      - The 'f' prefix means flags.  Flags are unsigned integers of some kind
     455 *        or booleans.
     456 *
     457 *      - TODO: need prefix for real float.  [type]
     458 *
     459 *      - The 'rd' prefix means real double and is used for 'double' variables.
     460 *        [type]
     461 *
     462 *      - The 'lrd' prefix means long real double and is used for 'long double'
     463 *        variables. [type]
     464 *
     465 *      - The 'ch' prefix means a char, the (signed) char type.  [type]
     466 *
     467 *      - The 'wc' prefix means a wide/windows char, the RTUTF16 type.  [type]
     468 *
     469 *      - The 'uc' prefix means a Unicode Code point, the RTUNICP type.  [type]
     470 *
     471 *      - The 'uch' prefix means unsigned char.  It's rarely used.  [type]
     472 *
     473 *      - The 'sz' prefix means zero terminated character string (array of
     474 *        chars). (UTF-8)
     475 *
     476 *      - The 'wsz' prefix means zero terminated wide/windows character string
     477 *        (array of RTUTF16).
     478 *
     479 *      - The 'usz' prefix means zero terminated Unicode string (array of
     480 *        RTUNICP).
    395481 *
    396482 *      - The 'str' prefix means C++ string; either a std::string or, in Main,
    397  *        a Utf8Str or, in Qt, a QString
    398  *
    399  *      - The 'bstr' prefix, in Main, means a UTF-16 Bstr.
     483 *        a Utf8Str or, in Qt, a QString.  When used with 'p', 'r', 'a' or 'c'
     484 *        the first letter should be capitalized.
     485 *
     486 *      - The 'bstr' prefix, in Main, means a UTF-16 Bstr. When used with 'p',
     487 *        'r', 'a' or 'c' the first letter should be capitalized.
    400488 *
    401489 *      - The 'pfn' prefix means pointer to function. Common usage is 'pfnCallback'
    402490 *        and such like.
     491 *
     492 *      - The 'psz' prefix is a combination of 'p' and 'sz' and thus means
     493 *        pointer to a zero terminated character string. (UTF-8)
     494 *
     495 *      - The 'pcsz' prefix is used to indicate constant string pointers in
     496 *        parts of the code.  Most code uses 'psz' for const and non-const
     497 *        string pointers.
     498 *
     499 *      - The 'l' prefix means (signed) long.  We try avoid using this,
     500 *        expecially with the 'LONG' types in Main as these are not 'long' on
     501 *        64-bit non-Windows platforms and can cause confusion. Alternatives:
     502 *        'i' or 'i32'.  [type]
     503 *
     504 *      - The 'ul' prefix means unsigned long.  We try avoid using this,
     505 *        expecially with the 'ULONG' types in Main as these are not 'unsigned
     506 *        long' on 64-bit non-Windows platforms and can cause confusion.
     507 *        Alternatives: 'u' or 'u32'.  [type]
    403508 *
    404509 *
Note: See TracChangeset for help on using the changeset viewer.

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