"Fossies" - the Fresh Open Source Software Archive 
Member "xorp/devnotes/coding-style.txt" (19 Jul 2010, 7110 Bytes) of package /linux/misc/xorp-1.8.5-src.tar.gz:
As a special service "Fossies" has tried to format the requested text file into HTML format (style:
standard) with prefixed line numbers.
Alternatively you can here
view or
download the uninterpreted source code file.
1 #
2 # $XORP: xorp/devnotes/coding-style.txt,v 1.6 2007/05/23 12:12:33 pavlin Exp $
3 #
4
5 Provisional XORP C++ coding style
6
7 This is a *provisional* attempt to lay down some rules that we can
8 adhere to and moan about. The style is only intended to apply to new
9 code, not code that we import. Hopefully, the style is equidistant
10 from our default coding styles that all are equally peturbed.
11
12 - DOCTRINE
13
14 Ignore any section of this document when doing so would enhance
15 readability. Feel free to edit someone else's code into agreement
16 with these principles, or into agreement with your own variant of
17 these principles. Expect that your code may be likewise edited.
18
19 - FILE PROLOGUES
20
21 Files should have a prologue containing the copyright, a description
22 of what the file does, an RCS version id, and an RCS
23 string/identifier in implementation files that ident(1) can use.
24
25 We have a standard templates to work from:
26 devnotes/template.hh
27 devnotes/template.cc
28 devnotes/template.h
29 devnotes/template.c
30
31 - INDENTATION
32
33 Use 4 spaces per indent level. Indentation should generally follow
34 "gnu". The default emacs c/c++ style is gnu, can be set with
35 M-x c-set-style gnu).
36
37 - BRACES
38
39 Try to avoid gratuitous newlines between statements opening a brace
40 and the opening brace. E.g., prefer:
41
42 if (abc == 3) {
43 /* XXX */
44 }
45
46 to:
47 if (abc == 3)
48 {
49 /* XXX */
50 }
51
52 For the sake of readability, try to place white space either side of
53 braces. E.g., prefer:
54 bool foo() { return _some_value; }
55 to:
56 bool foo() {return some_value;}
57
58 - REFERENCE AND POINTER ANNOTATIONS
59
60 Prefer:
61 foo(int& x) and bar(int* y)
62 to:
63 foo(int &x) and bar(int *y)
64
65 The former appears to be more widely used in C++ literature and so we go
66 with this for the sake of consistency.
67
68 - TEMPORARY REFERENCES
69
70 Temporary references can help make code more readable. When used
71 with containers to pointer types the resulting code can be more
72 readable and efficient.
73
74 static void process(const string& s); // Forward declaration
75
76 static void
77 process_long_names1(list<string*> names)
78 {
79 list<string*>::const_iterator ci;
80 for (ci = names.begin(); ci != names.end(); ++ci) {
81 if ((*ci)->size() > 10) { // Direct use of iterator
82 process(*(*ci));
83 }
84 }
85 }
86
87 static void
88 process_long_names2(list<string*> names)
89 {
90 list<string*>::const_iterator ci;
91 for (ci = names.begin(); ci != names.end(); ++ci) {
92 const string& s = *(*ci); // Use of temporary ref
93 if (s.size() > 10) {
94 process(s);
95 }
96 }
97 }
98
99 - COMMENTS
100
101 Use // for comments.
102
103 Avoid obvious comments inside routines. Any comments inside routines
104 should be short -- one line, when possible. Prefer single blank
105 lines for separating sections of code.
106
107 - API DOCUMENTATION (kdoc)
108
109 All major routines should have a comment briefly describing what
110 they do. We use kdoc comments (similar to javadoc) to generate API
111 overviews and programming documentation.
112
113 - TERMINAL WIDTH
114
115 Assume the terminal is 80 characters wide. Sure there'll be odd
116 times when wraps cannot be avoided, but gratuitous wrapping will
117 give you a "wide boy" reputation.
118
119 - CAPITALIZATION
120
121 class Wrench {
122 public:
123 Wrench() { ... };
124 ~Wrench() { ... };
125 apply_force();
126 ...
127 private:
128 double _weight;
129 };
130
131 Note that the class's public interface comes first.
132
133 - UNDERSCORING
134
135 Member variables should begin with an underscore. Regular variables
136 and function names should separate words with underscores.
137
138 Double underscores should never be used, they are often used by the
139 compiler during name munging.
140
141 - NAMES FOR MODIFIERS AND ACCESSORS.
142
143 Often, a private member variable will have associated public member
144 functions that get and/or set its value. If the variable is named
145 "_xxx", name the getter function "xxx()" and the setter function
146 "set_xxx()". The getter function should generally be const.
147
148 - STRING METHODS
149
150 When necesary to have a string method, call it str(). In general, try
151 to avoid adding operator string().
152
153 - BOOL METHODS
154
155 In general, always avoid adding operator bool(), unless there is a
156 strong reason for adding it.
157
158 - METHOD DEFINITIONS
159
160 When defining C++ in implementation files place the return value
161 and class/method declarations on separate lines. E.g.,
162
163 const char*
164 LuckyEightBall::speak() const
165 {
166 // blah blah
167 }
168
169 - ABBREVIATIONS
170
171 Should be avoided, especially in method names.
172
173 - INTEGER TYPES
174
175 Use integer types defined in inttypes.h, these are POSIX compatible
176 and portable.
177
178 - USE OF CONST
179
180 Decorate member functions with "const" whenever appropriate for
181 purposes of documentation. Member functions that do not alter an
182 object's value should be "const". Sometimes, a member variable is
183 altered by a function that does not conceptually change the object's
184 value. Mark such member variables as "mutable" to enhance the
185 applicability of "const".
186
187 - USE OF EXCEPTIONS AND STANDARD TEMPLATE LIBRARY
188
189 Non-kernel modules should use exceptions and the standard template
190 library where appropriate.
191
192 - USE OF AUTOCONF
193
194 We will use GNU autoconf to improve portability. The "xorp_config.h"
195 header file will define symbols specifying system properties that
196 may differ between reasonable Unices. This file is included by
197 "libxorp/xorp.h" which itself includes and defines a number of other
198 useful header files and features. The first file included by any XORP
199 source file should be "libxorp/xorp.h".
200 However, if one of the included header files is the module-specific
201 "foo_module.h" (required by "libxorp/xlog.h"), that file should
202 be included before "libxorp/xorp.h".
203
204 - INCLUDE FILES
205
206 Include files should be sorted into domain, each domain separated by
207 a blank line:
208
209 "foo_module.h"
210 "libxorp/xorp.h"
211 kernel includes
212 sys includes
213 net includes
214 default include path includes
215 XORP libraries includes
216 local includes
217
218 Don't sweat it too hard, however.
219
220 - SPACES AND PARENTHESES
221
222 Binary operators should have spaces around them to ease
223 decipherment. Parentheses have to used when precedence dictates and
224 can be used to reduce confusion, particularly with long
225 expressions. Do not put spaces around parentheses.
226
227 Keywords should likewise have spaces around them. For example,
228 `if (x)', not `if(x)'; and `return x', not `return(x)'.
229
230 - VARIABLE DECLARATIONS
231
232 Place variable declarations at the beginning of the relevant
233 scope. This includes placing declarations in the middle of
234 functions, close to their first uses, when appropriate. Declare
235 iteration variables inside the `for' statement when possible; this
236 is most of the time. Declare a test variable inside the `if' test
237 when possible; this happens comparatively rarely. Prefer multiple
238 declarations when defining several variables that require
239 initializers.
240
241 - PORTABILITY
242
243 All IPv6-specific code should be "#ifdef HAVE_IPV6" :
244 #ifdef HAVE_IPV6
245 ....
246 #endif // HAVE_IPV6
247
248 If there is only one line of code between #ifdef and #endif, then
249 do not add the comment after "#endif".
250