storage/style.txt

   1 Storage Module Style Guidelines
   2
   3 These guidelines should be followed for all new code in this module.  Reviewers
   4 will be enforcing them, so please obey them!
   5
   6 * All code should be contained within the namespace mozilla::storage at a
   7   minimum.  The use of namespaces is strongly encouraged.
   8
   9 * All functions being called in the global namespace should be prefixed with
  10   "::" to indicate that they are in the global namespace.
  11
  12 * The indentation level to use in source code is two spaces.  No tabs, please!
  13
  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\:>~ :
  17
  18 * All functions that are not XPCOM should start with a lowercase letter.
  19
  20 * Function arguments that are not out parameters should be prefixed with a (for
  21   pArameter), and use CamelCase.
  22
  23 * Function arguments that are out parameters should be prefixed with an
  24   underscore and have a descriptive name.
  25
  26 * Function declarations should include javadoc style comments.
  27
  28 * Javadoc @param tags should have the parameter description start on a new line
  29   aligned with the variable name.  See the example below.
  30
  31 * Javadoc @return (note: non-plural) continuation lines should be lined up with
  32   the initial comment.  See the example below.
  33
  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.
  37
  38 * For function implementations, each argument should be on its own line.
  39
  40 * All variables should use camelCase.
  41
  42 * The use of bool is encouraged whenever the variable does not have the
  43   potential to go through xpconnect.
  44
  45 * For pointer variable types, include a space after the type before the asterisk
  46   and no space between the asterisk and variable name.
  47
  48 * If any part of an if-else block requires braces, all blocks need braces.
  49
  50 * Every else should be on a newline after a brace.
  51
  52 * Bracing should start on the line after a function and class definition.  This
  53   goes for JavaScript code as well as C++ code.
  54
  55 * If a return value is not going to be checked, the return value should be
  56   explicitly casted to void (C style cast).
  57
  58
  59 BIG EXAMPLE:
  60
  61 *** Header ***
  62
  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/. */
  68
  69 #ifndef mozilla_storage_FILENAME_h_
  70 #define mozilla_storage_FILENAME_h_
  71
  72 namespace mozilla {
  73 namespace storage {
  74
  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 };
  96
  97 } // storage
  98 } // mozilla
  99
 100 #endif // mozilla_storage_FILENAME_h_
 101
 102
 103 *** Implementation ***
 104
 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/. */
 110
 111 NS_IMPL_ISUPPORTS(
 112   Foo
 113 , IBar
 114 , IBaz
 115 )
 116
 117 Foo::Foo(
 118   LongArgumentLineThatWouldOtherwiseOverflow *aArgument1
 119 )
 120 : mField1(0)
 121 , mField2(0)
 122 {
 123   someMethodWithLotsOfParamsOrJustLongParameters(
 124     mLongFieldNameThatIsJustified,
 125     mMaybeThisOneIsLessJustifiedButBoyIsItLong,
 126     15
 127   );
 128 }
 129
 130 ////////////////////////////////////////////////////////////////////////////////
 131 //// Separate sections of the file like this
 132
 133 int
 134 Foo::chew(int aArg1, int aArg2)
 135 {
 136   (void)functionReturningAnIgnoredValue();
 137
 138   ::functionFromGlobalNamespaceWithVoidReturnValue();
 139
 140   return 0;
 141 }