style.txt

Storage Module Style Guidelines

These guidelines should be followed for all new code in this module.  Reviewers
will be enforcing them, so please obey them!

* All code should be contained within the namespace mozilla::storage at a
  minimum.  The use of namespaces is strongly encouraged.

* All functions being called in the global namespace should be prefixed with
  "::" to indicate that they are in the global namespace.

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

* All files should have the following emacs and vim mode lines:
  -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*-
  vim: sw=2 ts=2 et lcs=trail\:.,tab\:>~ :

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

* Function arguments that are not out parameters should be prefixed with a (for
  pArameter), and use CamelCase.

* Function arguments that are out parameters should be prefixed with an
  underscore and have a descriptive name.

* Function declarations should include javadoc style comments.

* Javadoc @param tags should have the parameter description start on a new line
  aligned with the variable name.  See the example below.

* Javadoc @return (note: non-plural) continuation lines should be lined up with
  the initial comment.  See the example below.

* Javadoc @throws, like @param, should have the exception type on the same line
  as the @throws and the description on a new line indented to line up with
  the type of the exception.

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

* All variables should use camelCase.

* The use of bool is encouraged whenever the variable does not have the
  potential to go through xpconnect.

* For pointer variable types, include a space after the type before the asterisk
  and no space between the asterisk and variable name.

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

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

* Bracing should start on the line after a function and class definition.  This
  goes for JavaScript code as well as C++ code.

* If a return value is not going to be checked, the return value should be
  explicitly casted to void (C style cast).


BIG EXAMPLE:

*** Header ***

/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*-
 * vim: sw=2 ts=2 et lcs=trail\:.,tab\:>~ :
 * ***** BEGIN LICENSE BLOCK *****
...
 * ***** END LICENSE BLOCK ***** */

#ifndef mozilla_storage_FILENAME_h_
#define mozilla_storage_FILENAME_h_

namespace mozilla {
namespace storage {

class Foo : public Bar
          , public Baz
{
public:
  /**
   * Brief function summary.
   *
   * @param aArg1
   *        Description description description description description etc etc
   *        next line of description.
   * @param aArg2
   *        Description description description.
   * @return Description description description description description etc etc
   *         next line of description.
   *
   * @throws NS_ERROR_FAILURE
   *         Okay, so this is for JavaScript code, but you probably get the
   *         idea.
   */
  int chew(int aArg1, int aArg2);
};

} // storage
} // mozilla

#endif // mozilla_storage_FILENAME_h_


*** Implementation ***

/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*-
 * vim: sw=2 ts=2 et lcs=trail\:.,tab\:>~ :
 * ***** BEGIN LICENSE BLOCK *****
...
 * ***** END LICENSE BLOCK ***** */

NS_IMPL_THREADSAFE_ISUPPORTS2(
  Foo
, IBar
, IBaz
)

Foo::Foo(
  LongArgumentLineThatWouldOtherwiseOverflow *aArgument1
)
: mField1(0)
, mField2(0)
{
  someMethodWithLotsOfParamsOrJustLongParameters(
    mLongFieldNameThatIsJustified,
    mMaybeThisOneIsLessJustifiedButBoyIsItLong,
    15
  );
}

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

int
Foo::chew(int aArg1, int aArg2)
{
  (void)functionReturningAnIgnoredValue();

  ::functionFromGlobalNamespaceWithVoidReturnValue();

  return 0;
}