michael@0: Storage Module Style Guidelines
michael@0: 
michael@0: These guidelines should be followed for all new code in this module.  Reviewers
michael@0: will be enforcing them, so please obey them!
michael@0: 
michael@0: * All code should be contained within the namespace mozilla::storage at a
michael@0:   minimum.  The use of namespaces is strongly encouraged.
michael@0: 
michael@0: * All functions being called in the global namespace should be prefixed with
michael@0:   "::" to indicate that they are in the global namespace.
michael@0: 
michael@0: * The indentation level to use in source code is two spaces.  No tabs, please!
michael@0: 
michael@0: * All files should have the following emacs and vim mode lines:
michael@0:   -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*-
michael@0:   vim: sw=2 ts=2 et lcs=trail\:.,tab\:>~ :
michael@0: 
michael@0: * All functions that are not XPCOM should start with a lowercase letter.
michael@0: 
michael@0: * Function arguments that are not out parameters should be prefixed with a (for
michael@0:   pArameter), and use CamelCase.
michael@0: 
michael@0: * Function arguments that are out parameters should be prefixed with an
michael@0:   underscore and have a descriptive name.
michael@0: 
michael@0: * Function declarations should include javadoc style comments.
michael@0: 
michael@0: * Javadoc @param tags should have the parameter description start on a new line
michael@0:   aligned with the variable name.  See the example below.
michael@0: 
michael@0: * Javadoc @return (note: non-plural) continuation lines should be lined up with
michael@0:   the initial comment.  See the example below.
michael@0: 
michael@0: * Javadoc @throws, like @param, should have the exception type on the same line
michael@0:   as the @throws and the description on a new line indented to line up with
michael@0:   the type of the exception.
michael@0: 
michael@0: * For function implementations, each argument should be on its own line.
michael@0: 
michael@0: * All variables should use camelCase.
michael@0: 
michael@0: * The use of bool is encouraged whenever the variable does not have the
michael@0:   potential to go through xpconnect.
michael@0: 
michael@0: * For pointer variable types, include a space after the type before the asterisk
michael@0:   and no space between the asterisk and variable name.
michael@0: 
michael@0: * If any part of an if-else block requires braces, all blocks need braces.
michael@0: 
michael@0: * Every else should be on a newline after a brace.
michael@0: 
michael@0: * Bracing should start on the line after a function and class definition.  This
michael@0:   goes for JavaScript code as well as C++ code.
michael@0: 
michael@0: * If a return value is not going to be checked, the return value should be
michael@0:   explicitly casted to void (C style cast).
michael@0: 
michael@0: 
michael@0: BIG EXAMPLE:
michael@0: 
michael@0: *** Header ***
michael@0: 
michael@0: /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*-
michael@0:  * vim: sw=2 ts=2 et lcs=trail\:.,tab\:>~ : */
michael@0: /* This Source Code Form is subject to the terms of the Mozilla Public
michael@0:  * License, v. 2.0. If a copy of the MPL was not distributed with this
michael@0:  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
michael@0: 
michael@0: #ifndef mozilla_storage_FILENAME_h_
michael@0: #define mozilla_storage_FILENAME_h_
michael@0: 
michael@0: namespace mozilla {
michael@0: namespace storage {
michael@0: 
michael@0: class Foo : public Bar
michael@0:           , public Baz
michael@0: {
michael@0: public:
michael@0:   /**
michael@0:    * Brief function summary.
michael@0:    *
michael@0:    * @param aArg1
michael@0:    *        Description description description description description etc etc
michael@0:    *        next line of description.
michael@0:    * @param aArg2
michael@0:    *        Description description description.
michael@0:    * @return Description description description description description etc etc
michael@0:    *         next line of description.
michael@0:    *
michael@0:    * @throws NS_ERROR_FAILURE
michael@0:    *         Okay, so this is for JavaScript code, but you probably get the
michael@0:    *         idea.
michael@0:    */
michael@0:   int chew(int aArg1, int aArg2);
michael@0: };
michael@0: 
michael@0: } // storage
michael@0: } // mozilla
michael@0: 
michael@0: #endif // mozilla_storage_FILENAME_h_
michael@0: 
michael@0: 
michael@0: *** Implementation ***
michael@0: 
michael@0: /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*-
michael@0:  * vim: sw=2 ts=2 et lcs=trail\:.,tab\:>~ : */
michael@0: /* This Source Code Form is subject to the terms of the Mozilla Public
michael@0:  * License, v. 2.0. If a copy of the MPL was not distributed with this
michael@0:  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
michael@0: 
michael@0: NS_IMPL_ISUPPORTS(
michael@0:   Foo
michael@0: , IBar
michael@0: , IBaz
michael@0: )
michael@0: 
michael@0: Foo::Foo(
michael@0:   LongArgumentLineThatWouldOtherwiseOverflow *aArgument1
michael@0: )
michael@0: : mField1(0)
michael@0: , mField2(0)
michael@0: {
michael@0:   someMethodWithLotsOfParamsOrJustLongParameters(
michael@0:     mLongFieldNameThatIsJustified,
michael@0:     mMaybeThisOneIsLessJustifiedButBoyIsItLong,
michael@0:     15
michael@0:   );
michael@0: }
michael@0: 
michael@0: ////////////////////////////////////////////////////////////////////////////////
michael@0: //// Separate sections of the file like this
michael@0: 
michael@0: int
michael@0: Foo::chew(int aArg1, int aArg2)
michael@0: {
michael@0:   (void)functionReturningAnIgnoredValue();
michael@0: 
michael@0:   ::functionFromGlobalNamespaceWithVoidReturnValue();
michael@0: 
michael@0:   return 0;
michael@0: }