1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/storage/style.txt Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,141 @@
1.4 +Storage Module Style Guidelines
1.5 +
1.6 +These guidelines should be followed for all new code in this module. Reviewers
1.7 +will be enforcing them, so please obey them!
1.8 +
1.9 +* All code should be contained within the namespace mozilla::storage at a
1.10 + minimum. The use of namespaces is strongly encouraged.
1.11 +
1.12 +* All functions being called in the global namespace should be prefixed with
1.13 + "::" to indicate that they are in the global namespace.
1.14 +
1.15 +* The indentation level to use in source code is two spaces. No tabs, please!
1.16 +
1.17 +* All files should have the following emacs and vim mode lines:
1.18 + -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*-
1.19 + vim: sw=2 ts=2 et lcs=trail\:.,tab\:>~ :
1.20 +
1.21 +* All functions that are not XPCOM should start with a lowercase letter.
1.22 +
1.23 +* Function arguments that are not out parameters should be prefixed with a (for
1.24 + pArameter), and use CamelCase.
1.25 +
1.26 +* Function arguments that are out parameters should be prefixed with an
1.27 + underscore and have a descriptive name.
1.28 +
1.29 +* Function declarations should include javadoc style comments.
1.30 +
1.31 +* Javadoc @param tags should have the parameter description start on a new line
1.32 + aligned with the variable name. See the example below.
1.33 +
1.34 +* Javadoc @return (note: non-plural) continuation lines should be lined up with
1.35 + the initial comment. See the example below.
1.36 +
1.37 +* Javadoc @throws, like @param, should have the exception type on the same line
1.38 + as the @throws and the description on a new line indented to line up with
1.39 + the type of the exception.
1.40 +
1.41 +* For function implementations, each argument should be on its own line.
1.42 +
1.43 +* All variables should use camelCase.
1.44 +
1.45 +* The use of bool is encouraged whenever the variable does not have the
1.46 + potential to go through xpconnect.
1.47 +
1.48 +* For pointer variable types, include a space after the type before the asterisk
1.49 + and no space between the asterisk and variable name.
1.50 +
1.51 +* If any part of an if-else block requires braces, all blocks need braces.
1.52 +
1.53 +* Every else should be on a newline after a brace.
1.54 +
1.55 +* Bracing should start on the line after a function and class definition. This
1.56 + goes for JavaScript code as well as C++ code.
1.57 +
1.58 +* If a return value is not going to be checked, the return value should be
1.59 + explicitly casted to void (C style cast).
1.60 +
1.61 +
1.62 +BIG EXAMPLE:
1.63 +
1.64 +*** Header ***
1.65 +
1.66 +/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*-
1.67 + * vim: sw=2 ts=2 et lcs=trail\:.,tab\:>~ : */
1.68 +/* This Source Code Form is subject to the terms of the Mozilla Public
1.69 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.70 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.71 +
1.72 +#ifndef mozilla_storage_FILENAME_h_
1.73 +#define mozilla_storage_FILENAME_h_
1.74 +
1.75 +namespace mozilla {
1.76 +namespace storage {
1.77 +
1.78 +class Foo : public Bar
1.79 + , public Baz
1.80 +{
1.81 +public:
1.82 + /**
1.83 + * Brief function summary.
1.84 + *
1.85 + * @param aArg1
1.86 + * Description description description description description etc etc
1.87 + * next line of description.
1.88 + * @param aArg2
1.89 + * Description description description.
1.90 + * @return Description description description description description etc etc
1.91 + * next line of description.
1.92 + *
1.93 + * @throws NS_ERROR_FAILURE
1.94 + * Okay, so this is for JavaScript code, but you probably get the
1.95 + * idea.
1.96 + */
1.97 + int chew(int aArg1, int aArg2);
1.98 +};
1.99 +
1.100 +} // storage
1.101 +} // mozilla
1.102 +
1.103 +#endif // mozilla_storage_FILENAME_h_
1.104 +
1.105 +
1.106 +*** Implementation ***
1.107 +
1.108 +/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*-
1.109 + * vim: sw=2 ts=2 et lcs=trail\:.,tab\:>~ : */
1.110 +/* This Source Code Form is subject to the terms of the Mozilla Public
1.111 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.112 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.113 +
1.114 +NS_IMPL_ISUPPORTS(
1.115 + Foo
1.116 +, IBar
1.117 +, IBaz
1.118 +)
1.119 +
1.120 +Foo::Foo(
1.121 + LongArgumentLineThatWouldOtherwiseOverflow *aArgument1
1.122 +)
1.123 +: mField1(0)
1.124 +, mField2(0)
1.125 +{
1.126 + someMethodWithLotsOfParamsOrJustLongParameters(
1.127 + mLongFieldNameThatIsJustified,
1.128 + mMaybeThisOneIsLessJustifiedButBoyIsItLong,
1.129 + 15
1.130 + );
1.131 +}
1.132 +
1.133 +////////////////////////////////////////////////////////////////////////////////
1.134 +//// Separate sections of the file like this
1.135 +
1.136 +int
1.137 +Foo::chew(int aArg1, int aArg2)
1.138 +{
1.139 + (void)functionReturningAnIgnoredValue();
1.140 +
1.141 + ::functionFromGlobalNamespaceWithVoidReturnValue();
1.142 +
1.143 + return 0;
1.144 +}
