tor-browser

The Tor Browser
git clone https://git.dasho.dev/tor-browser.git
Log | Files | Refs | README | LICENSE

style.txt (4303B)

      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 }