The Tor Browser: storage/style.txt@b8a032363ba2

Incorporate requested changes from Mozilla in review:
https://bugzilla.mozilla.org/show_bug.cgi?id=1123480#c6

     1 Storage Module Style Guidelines

     3 These guidelines should be followed for all new code in this module.  Reviewers

     4 will be enforcing them, so please obey them!

     6 * All code should be contained within the namespace mozilla::storage at a

     7   minimum.  The use of namespaces is strongly encouraged.

     9 * All functions being called in the global namespace should be prefixed with

    10   "::" to indicate that they are in the global namespace.

    12 * The indentation level to use in source code is two spaces.  No tabs, please!

    14 * All files should have the following emacs and vim mode lines:

    15   -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*-

    16   vim: sw=2 ts=2 et lcs=trail\:.,tab\:>~ :

    18 * All functions that are not XPCOM should start with a lowercase letter.

    20 * Function arguments that are not out parameters should be prefixed with a (for

    21   pArameter), and use CamelCase.

    23 * Function arguments that are out parameters should be prefixed with an

    24   underscore and have a descriptive name.

    26 * Function declarations should include javadoc style comments.

    28 * Javadoc @param tags should have the parameter description start on a new line

    29   aligned with the variable name.  See the example below.

    31 * Javadoc @return (note: non-plural) continuation lines should be lined up with

    32   the initial comment.  See the example below.

    34 * Javadoc @throws, like @param, should have the exception type on the same line

    35   as the @throws and the description on a new line indented to line up with

    36   the type of the exception.

    38 * For function implementations, each argument should be on its own line.

    40 * All variables should use camelCase.

    42 * The use of bool is encouraged whenever the variable does not have the

    43   potential to go through xpconnect.

    45 * For pointer variable types, include a space after the type before the asterisk

    46   and no space between the asterisk and variable name.

    48 * If any part of an if-else block requires braces, all blocks need braces.

    50 * Every else should be on a newline after a brace.

    52 * Bracing should start on the line after a function and class definition.  This

    53   goes for JavaScript code as well as C++ code.

    55 * If a return value is not going to be checked, the return value should be

    56   explicitly casted to void (C style cast).

    59 BIG EXAMPLE:

    61 *** Header ***

    63 /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*-

    64  * vim: sw=2 ts=2 et lcs=trail\:.,tab\:>~ : */

    65 /* This Source Code Form is subject to the terms of the Mozilla Public

    66  * License, v. 2.0. If a copy of the MPL was not distributed with this

    67  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */

    69 #ifndef mozilla_storage_FILENAME_h_

    70 #define mozilla_storage_FILENAME_h_

    72 namespace mozilla {

    73 namespace storage {

    75 class Foo : public Bar

    76           , public Baz

    77 {

    78 public:

    79   /**

    80    * Brief function summary.

    81    *

    82    * @param aArg1

    83    *        Description description description description description etc etc

    84    *        next line of description.

    85    * @param aArg2

    86    *        Description description description.

    87    * @return Description description description description description etc etc

    88    *         next line of description.

    89    *

    90    * @throws NS_ERROR_FAILURE

    91    *         Okay, so this is for JavaScript code, but you probably get the

    92    *         idea.

    93    */

    94   int chew(int aArg1, int aArg2);

    95 };

    97 } // storage

    98 } // mozilla

   100 #endif // mozilla_storage_FILENAME_h_

   103 *** Implementation ***

   105 /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*-

   106  * vim: sw=2 ts=2 et lcs=trail\:.,tab\:>~ : */

   107 /* This Source Code Form is subject to the terms of the Mozilla Public

   108  * License, v. 2.0. If a copy of the MPL was not distributed with this

   109  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */

   111 NS_IMPL_ISUPPORTS(

   112   Foo

   113 , IBar

   114 , IBaz

   115 )

   117 Foo::Foo(

   118   LongArgumentLineThatWouldOtherwiseOverflow *aArgument1

   119 )

   120 : mField1(0)

   121 , mField2(0)

   122 {

   123   someMethodWithLotsOfParamsOrJustLongParameters(

   124     mLongFieldNameThatIsJustified,

   125     mMaybeThisOneIsLessJustifiedButBoyIsItLong,

   126     15

   127   );

   128 }

   130 ////////////////////////////////////////////////////////////////////////////////

   131 //// Separate sections of the file like this

   133 int

   134 Foo::chew(int aArg1, int aArg2)

   135 {

   136   (void)functionReturningAnIgnoredValue();

   138   ::functionFromGlobalNamespaceWithVoidReturnValue();

   140   return 0;

   141 }

The Tor Browser / file revision