Merge mozilla-central to autoland on a CLOSED TREE
[gecko.git] / storage / style.txt
blob03652e6066ec886d4469c00529c18667a855294c
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
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);
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
117 Foo::Foo(
118   LongArgumentLineThatWouldOtherwiseOverflow *aArgument1
120 : mField1(0)
121 , mField2(0)
123   someMethodWithLotsOfParamsOrJustLongParameters(
124     mLongFieldNameThatIsJustified,
125     mMaybeThisOneIsLessJustifiedButBoyIsItLong,
126     15
127   );
130 ////////////////////////////////////////////////////////////////////////////////
131 //// Separate sections of the file like this
134 Foo::chew(int aArg1, int aArg2)
136   (void)functionReturningAnIgnoredValue();
138   ::functionFromGlobalNamespaceWithVoidReturnValue();
140   return 0;