Project

General

Profile

CodeStyle » History » Version 24

Alex Afanasyev, 04/07/2014 04:04 PM

1 1 Junxiao Shi
# NFD code style guidelines
2
3
NFD adopts [NDN Platform C++, C, C#, Java and JavaScript Code Guidelines](http://named-data.net/codebase/platform/documentation/ndn-platform-development-guidelines/cpp-code-guidelines/), with the following exceptions:
4
5 10 Alex Afanasyev
*   (amended 8) Names representing generic template types should be a single uppercase letter
6
7
        template<class T> ...
8
        template<class C, class D> ...
9
10
    However, when template parameter represents a certain concept and expected to have a certain interface, the name should be explicitly spelled out:
11
12
        template<class FaceBase> ...
13
        template<class Packet> ...
14
15 8 Junxiao Shi
*   (amended 10)
16
    Global variables should have `g_` prefix
17 1 Junxiao Shi
18 8 Junxiao Shi
*   (amended 11)
19 15 Alex Afanasyev
    **Private** class variables should have `m_` prefix.
20
    **Static** class variables should have `s_` prefix.
21 8 Junxiao Shi
22 11 Alex Afanasyev
*   (amended 26)
23
    Allow commonly used abbreviated **next/prev** pair in addition to **next/previous**
24
25 12 Alex Afanasyev
    Pair **insert/erase** should be used for any new code, already implemented code can keep **insert/delete** if it does not conflict with C++ delete keyword.
26
27 13 Alex Afanasyev
*   (amended 27)
28 14 Alex Afanasyev
    In cases when full word is too long, a commonly accepted abbreviation can be used.  For example, **dest** instead of **destination**.
29 13 Alex Afanasyev
30 8 Junxiao Shi
*   (amended 31)
31
    Exceptions can be used in the code, but should be used only in **exceptional** cases and not in the primary processing path.
32
33
    Exceptions can be suffixed with either `Exception` (eg. SecurityException) or `Error` (eg. SecurityError).  Alternatively (and it is a recommended method), one should declare exception class `Exception` or `Error` as an inner class, from which the exception is thrown. For example, when declaring class Foo that can throw errors, one can write the following:
34
35 5 Alex Afanasyev
        #include <stdexcept>
36 1 Junxiao Shi
        
37
        class Foo
38 5 Alex Afanasyev
        {
39 24 Alex Afanasyev
          class Error : public std::runtime_error
40 20 Alex Afanasyev
          {
41
          public:
42
            explicit
43
            Error(const std::string& what)
44
              : std::runtime_error(what)
45 1 Junxiao Shi
            {
46 20 Alex Afanasyev
            }
47
          };
48
        };  
49 1 Junxiao Shi
50 8 Junxiao Shi
    In addition to that, if class Foo is a base class or interface for some class hierarchy, then child classes should should define their own `Error` or `Exception` classes that are inherited from the parent's Error class.
51
52 1 Junxiao Shi
*   (amended 33)
53 8 Junxiao Shi
    We will use only `.cpp` and `.hpp` extensions
54 17 Davide Pesavento
55 8 Junxiao Shi
*   (removed 35)
56 18 Alex Afanasyev
    Lines should be within a reasonable range. Lines longer than 100 columns should generally be avoided.
57
58
*   (updated 37)
59
    Exceptions:
60
61
    * The following is the standard practice with ``operator<<``:
62
63
            std::cout << "Something here "
64 8 Junxiao Shi
                      << "Something there" << std::endl;
65
66
*   (removed 44)
67
    Implicit conversion is generally allowed.
68
69
    Implicit conversion between integer and floating point numbers can cause problems and should be avoided.
70
71
    Implicit conversion in single-argument constructor is usually undesirable. Therefore, all single-argument constructors should be marked 'explicit', unless implicit conversion is desirable. In that case, a comment should document the reason.
72
73 21 Alex Afanasyev
    Avoid C-style casts.  Use `static_cast`, `dynamic_cast`, `reinterpret_cast`, `const_cast` instead where appropriate.  Use `static_pointer_cast`, `dynamic_pointer_cast`, `const_pointer_cast` when dealing with `shared_ptr`.
74 17 Davide Pesavento
75 16 Alex Afanasyev
*   (replaced 48)
76 17 Davide Pesavento
    In most cases, class instance variables should never be declared public.
77 16 Alex Afanasyev
    
78 8 Junxiao Shi
    The concepts of information hiding and encapsulation are violated by public variables. Use private variables and access methods instead. One exception to this rule is when the class is essentially a dumb data structure with no behavior (equivalent to a C struct, also known as PODS).  In this case it is appropriate to make the instance variables public by using ``struct``.
79
80
*   (amended 68)
81
    All three presented styles ARE acceptable.  First and third ARE recommended (these are actually GNU styles).
82
83
*   (amended 69)
84 3 Alex Afanasyev
    The class declarations should have the following form:
85 4 Junxiao Shi
86 3 Alex Afanasyev
        class SomeClass : public BaseClass 
87 4 Junxiao Shi
        { 
88 3 Alex Afanasyev
        public: 
89
          ... <public methods> ...
90
        protected: 
91 1 Junxiao Shi
          ... <protected methods> ...
92
        private: 
93
          ... <private methods> ...
94
        
95 3 Alex Afanasyev
        public: 
96
          ... <public data> ...
97
        protected: 
98
          ... <protected data> ...
99
        private: 
100
          ... <private data> ...
101
        };
102
103 8 Junxiao Shi
    ``public``, ``protected``, ``private`` may be repeated several times without interleaving (e.g. public, public, public, private, private) if this allows better readability of the code.
104
105
*   (amended 70)
106
    When declaring/defining function/method, the return type should be put on a separate line before function/method name.
107 3 Alex Afanasyev
108
    Method and function definitions should have the following form:
109
110
        void
111
        someMethod() 
112 1 Junxiao Shi
        { 
113 9 Alex Afanasyev
          ... 
114
        }
115
116 23 Alex Afanasyev
*   (changed 76) `switch` statement should have one of the two of following forms:
117 1 Junxiao Shi
118 22 Alex Afanasyev
        switch (condition) {
119
        case ABC:
120
          statements;
121
          // Fallthrough
122
123
        case DEF:
124
          statements;
125
          break;
126
127
        case XYZ:
128
          statements;
129
          break;
130
131
        default:
132
          statements;
133
          break;
134
        }
135
136
    or
137
138
        switch (condition)
139
          {
140 1 Junxiao Shi
          case ABC:
141 22 Alex Afanasyev
            statements;
142
            // Fallthrough
143
144
          case DEF:
145
            statements;
146 19 Alex Afanasyev
            break;
147 22 Alex Afanasyev
148
          case XYZ:
149
            statements;
150 19 Alex Afanasyev
            break;
151 22 Alex Afanasyev
152
          default:
153
            statements;
154
            break;
155
          }
156 19 Alex Afanasyev
157
## Python addition
158
159
Most of the provisions in the above style guidance apply to Python as well.  For python-specific elements, [PEP 8](http://legacy.python.org/dev/peps/pep-0008/) can be used as a reference coding style.  
160
161 1 Junxiao Shi
The following is few rules directly adopted from [PEP 8](http://legacy.python.org/dev/peps/pep-0008/):
162
163
* **P1**  Always surround these binary operators with a single space on either side: assignment (=), augmented assignment (+=, -= etc.), comparisons (==, <, >, !=, <>, <=, >=, in, not in, is, is not), Booleans (and, or, not).
164
165
        def complex(real, imag=0.0):
166
            value = 1.1
167
            return magic(r=real + value, i=imag)
168
169
* **P2** Don't use spaces around the = sign when used to indicate a keyword argument or a default parameter value.
170
171
        def complex(real, imag=0.0):
172
            return magic(r=real, i=imag)