ceph/CodingStyle

   1 Ceph Coding style
   2 -----------------
   3
   4 Coding style is most important for new code and (to a lesser extent)
   5 revised code.  It is not worth the churn to simply reformat old code.
   6
   7 C code
   8 ------
   9
  10 For C code, we conform by the Linux kernel coding standards:
  11
  12     https://www.kernel.org/doc/Documentation/process/coding-style.rst
  13
  14
  15 C++ code
  16 --------
  17
  18 For C++ code, things are a bit more complex.  As a baseline, we use Google's
  19 coding guide:
  20
  21     https://google.github.io/styleguide/cppguide.html
  22
  23
  24 As an addendum to the above, we add the following guidelines, organized
  25 by section.
  26
  27 * Naming > Type Names:
  28
  29     Google uses CamelCaps for all type names.  We use two naming schemes:
  30
  31     - for naked structs (simple data containers), lower case with _t.
  32       Yes, _t also means typedef.  It's perhaps not ideal.
  33
  34         struct my_type_t {
  35           int a = 0, b = 0;
  36           void encode(...) ...
  37           ...
  38         };
  39
  40     - for full-blown classes, CamelCaps, private: section, accessors,
  41       probably not copyable, etc.
  42
  43 * Naming > Variable Names:
  44
  45    Google uses _ suffix for class members.  That's ugly.  We'll use
  46    a m_ prefix, like so, or none at all.
  47
  48         class Foo {
  49          public:
  50           int get_foo() const { return m_foo; }
  51           void set_foo(int foo) { m_foo = foo; }
  52
  53          private:
  54           int m_foo;
  55         };
  56
  57 * Naming > Constant Names:
  58
  59    Google uses kSomeThing for constants.  We prefer SOME_THING.
  60
  61 * Naming > Function Names:
  62
  63    Google uses CamelCaps.  We use_function_names_with_underscores().
  64
  65    Accessors are the same, {get,set}_field().
  66
  67 * Naming > Enumerator Names:
  68
  69    Name them like constants, as above (SOME_THING).
  70
  71 * Comments > File Comments:
  72
  73    Don't sweat it, unless the license varies from that of the project
  74    (LGPL2.1 or LGPL3.0) or the code origin isn't reflected by the git history.
  75
  76 * Formatting > Tabs:
  77   Indent width is two spaces.  When runs of 8 spaces can be compressed
  78   to a single tab character, do so. The standard Emacs/Vim settings
  79   header is:
  80
  81 // -*- mode:C++; tab-width:8; c-basic-offset:2; indent-tabs-mode:t -*-
  82 // vim: ts=8 sw=2 smarttab ft=cpp
  83
  84 * Formatting > Conditionals:
  85
  86    - No spaces inside conditionals please, e.g.
  87
  88         if (foo) {   // okay
  89
  90         if ( foo ) { // no
  91
  92    - Always use newline following if, and use braces:
  93
  94         if (foo) {
  95           bar;         // like this, even for a one-liner
  96         }
  97
  98         if (foo)
  99           bar;         // no, usually harder to parse visually
 100
 101         if (foo) bar;  // no
 102
 103         if (foo) { bar; }  // definitely no
 104
 105 * Header Files -> The `#define` Guard:
 106
 107   `#pragma once` is allowed for simplicity at the expense of
 108    portability since `#pragma once` is widely supported and is known
 109    to work on GCC and Clang.
 110
 111
 112 The following guidelines have not been followed in the legacy code,
 113 but are worth mentioning and should be followed strictly for new code:
 114
 115 * Header Files > Function Parameter Ordering:
 116
 117     Inputs, then outputs.
 118
 119 * Classes > Explicit Constructors:
 120
 121     You should normally mark constructors explicit to avoid getting silent
 122 type conversions.
 123
 124 * Classes > Copy Constructors:
 125
 126     - Use defaults for basic struct-style data objects.
 127
 128     - Most other classes should DISALLOW_COPY_AND_ASSIGN.
 129
 130     - In rare cases we can define a proper copy constructor and operator=.
 131
 132 * Other C++ Features > Reference Arguments:
 133
 134     Only use const references.  Use pointers for output arguments.
 135
 136 * Other C++ Features > Avoid Default Arguments:
 137
 138     They obscure the interface.
 139
 140
 141 Python code
 142 -----------
 143
 144 For new python code, PEP-8 should be observed:
 145
 146     https://www.python.org/dev/peps/pep-0008/
 147
 148 Existing code can be refactored to adhere to PEP-8, and cleanups are welcome.
 149
 150
 151 JavaScript / TypeScript
 152 -----------------------
 153
 154 For Angular code, we follow the official Angular style guide:
 155
 156     https://angular.io/guide/styleguide
 157
 158 To check whether your code is conformant with the style guide, we use a
 159 combination of TSLint, Codelyzer and Prettier:
 160
 161     https://palantir.github.io/tslint/
 162     http://codelyzer.com/
 163     https://prettier.io/
 164