1 Open vSwitch Coding Style
2 =========================
4 This file describes the coding style used in most C files in the Open
5 vSwitch distribution. However, Linux kernel code datapath directory
6 follows the Linux kernel's established coding conventions.
10 Limit lines to 79 characters.
12 Use form feeds (control+L) to divide long source files into logical
13 pieces. A form feed should appear as the only character on a line.
15 Do not use tabs for indentation.
17 Avoid trailing spaces on lines.
22 Use names that explain the purpose of a function or object.
24 Use underscores to separate words in an identifier: multi_word_name.
26 Use lowercase for most names. Use uppercase for macros, macro
27 parameters, and members of enumerations.
29 Give arrays names that are plural.
31 Pick a unique name prefix (ending with an underscore) for each
32 module, and apply that prefix to all of that module's externally
33 visible names. Names of macro parameters, struct and union members,
34 and parameters in function prototypes are not considered externally
35 visible for this purpose.
37 Do not use names that begin with _. If you need a name for
38 "internal use only", use __ as a suffix instead of a prefix.
40 Avoid negative names: "found" is a better name than "not_found".
42 In names, a "size" is a count of bytes, a "length" is a count of
43 characters. A buffer has size, but a string has length. The length
44 of a string does not include the null terminator, but the size of the
45 buffer that contains the string does.
50 Comments should be written as full sentences that start with a
51 capital letter and end with a period. Put two spaces between
54 Write block comments as shown below. You may put the /* and */ on
55 the same line as comment text if you prefer.
58 * We redirect stderr to /dev/null because we often want to remove all
59 * traffic control configuration on a port so its in a known state. If
60 * this done when there is no such configuration, tc complains, so we just
64 Each function and each variable declared outside a function, and
65 each struct, union, and typedef declaration should be preceded by a
66 comment. See FUNCTION DEFINITIONS below for function comment
69 Each struct and union member should each have an inline comment that
70 explains its meaning. structs and unions with many members should be
71 additionally divided into logical groups of members by block comments,
74 /* An event that will wake the following call to poll_block(). */
76 /* Set when the waiter is created. */
77 struct list node; /* Element in global waiters list. */
78 int fd; /* File descriptor. */
79 short int events; /* Events to wait for (POLLIN, POLLOUT). */
80 poll_fd_func *function; /* Callback function, if any, or null. */
81 void *aux; /* Argument to callback function. */
82 struct backtrace *backtrace; /* Event that created waiter, or null. */
84 /* Set only when poll_block() is called. */
85 struct pollfd *pollfd; /* Pointer to element of the pollfds array
86 (null if added from a callback). */
89 Use XXX or FIXME comments to mark code that needs work.
91 Don't use // comments.
93 Don't comment out or #if 0 out code. Just remove it. The code that
94 was there will still be in version control history.
99 Put the return type, function name, and the braces that surround the
100 function's code on separate lines, all starting in column 0.
102 Before each function definition, write a comment that describes the
103 function's purpose, including each parameter, the return value, and
104 side effects. References to argument names should be given in
105 single-quotes, e.g. 'arg'. The comment should not include the
106 function name, nor need it follow any formal structure. The comment
107 does not need to describe how a function does its work, unless this
108 information is needed to use the function correctly (this is often
109 better done with comments *inside* the function).
111 Simple static functions do not need a comment.
113 Within a file, non-static functions should come first, in the order
114 that they are declared in the header file, followed by static
115 functions. Static functions should be in one or more separate pages
116 (separated by form feed characters) in logical groups. A commonly
117 useful way to divide groups is by "level", with high-level functions
118 first, followed by groups of progressively lower-level functions.
119 This makes it easy for the program's reader to see the top-down
120 structure by reading from top to bottom.
122 All function declarations and definitions should include a
123 prototype. Empty parentheses, e.g. "int foo();", do not include a
124 prototype (they state that the function's parameters are unknown);
125 write "void" in parentheses instead, e.g. "int foo(void);".
127 Prototypes for static functions should either all go at the top of
128 the file, separated into groups by blank lines, or they should appear
129 at the top of each page of functions. Don't comment individual
130 prototypes, but a comment on each group of prototypes is often
133 In the absence of good reasons for another order, the following
134 parameter order is preferred. One notable exception is that data
135 parameters and their corresponding size parameters should be paired.
137 1. The primary object being manipulated, if any (equivalent to the
138 "this" pointer in C++).
139 2. Input-only parameters.
140 3. Input/output parameters.
141 4. Output-only parameters.
146 /* Stores the features supported by 'netdev' into each of '*current',
147 * '*advertised', '*supported', and '*peer' that are non-null. Each value
148 * is a bitmap of "enum ofp_port_features" bits, in host byte order.
149 * Returns 0 if successful, otherwise a positive errno value. On failure,
150 * all of the passed-in values are set to 0. */
152 netdev_get_features(struct netdev *netdev,
153 uint32_t *current, uint32_t *advertised,
154 uint32_t *supported, uint32_t *peer)
162 Put the return type and function name on the same line in a function
165 static const struct option_class *get_option_class(int code);
168 Omit parameter names from function prototypes when the names do not
169 give useful information, e.g.:
171 int netdev_get_mtu(const struct netdev *, int *mtup);
176 Indent each level of code with 4 spaces. Use BSD-style brace
184 Put a space between "if", "while", "for", etc. and the expressions
187 Enclose single statements in braces:
195 Use comments and blank lines to divide long functions into logical
196 groups of statements.
198 Avoid assignments inside "if" and "while" conditions.
200 Do not put gratuitous parentheses around the expression in a return
201 statement, that is, write "return 0;" and not "return(0);"
203 Write only one statement per line.
205 Indent "switch" statements like this:
207 switch (conn->state) {
209 error = run_connection_input(conn);
217 error = run_connection_output(conn);
224 "switch" statements with very short, uniform cases may use an
228 case 200: return "OK";
229 case 201: return "Created";
230 case 202: return "Accepted";
231 case 204: return "No Content";
232 default: return "Unknown";
235 Use "for (;;)" to write an infinite loop.
237 In an if/else construct where one branch is the "normal" or "common"
238 case and the other branch is the "uncommon" or "error" case, put the
239 common case after the "if", not the "else". This is a form of
240 documentation. It also places the most important code in sequential
241 order without forcing the reader to visually skip past less important
242 details. (Some compilers also assume that the "if" branch is the more
243 common case, so this can be a real form of optimization as well.)
248 Don't define an object-like macro if an enum can be used instead.
250 Don't define a function-like macro if a "static inline" function
253 If a macro's definition contains multiple statements, enclose them
254 with "do { ... } while (0)" to allow them to work properly in all
255 syntactic circumstances.
257 Do use macros to eliminate the need to update different parts of a
258 single file in parallel, e.g. a list of enums and an array that gives
259 the name of each enum. For example:
261 /* Logging importance levels. */
262 #define VLOG_LEVELS \
263 VLOG_LEVEL(EMER, LOG_ALERT) \
264 VLOG_LEVEL(ERR, LOG_ERR) \
265 VLOG_LEVEL(WARN, LOG_WARNING) \
266 VLOG_LEVEL(INFO, LOG_NOTICE) \
267 VLOG_LEVEL(DBG, LOG_DEBUG)
269 #define VLOG_LEVEL(NAME, SYSLOG_LEVEL) VLL_##NAME,
275 /* Name for each logging level. */
276 static const char *level_names[VLL_N_LEVELS] = {
277 #define VLOG_LEVEL(NAME, SYSLOG_LEVEL) #NAME,
285 Each source file should state its license in a comment at the very
286 top, followed by a comment explaining the purpose of the code that is
287 in that file. The comment should explain how the code in the file
288 relates to code in other files. The goal is to allow a programmer to
289 quickly figure out where a given module fits into the larger system.
291 The first non-comment line in a .c source file should be:
295 #include directives should appear in the following order:
297 1. #include <config.h>
299 2. The module's own headers, if any. Including this before any
300 other header (besides <config.h>) ensures that the module's
301 header file is self-contained (see HEADER FILES) below.
303 3. Standard C library headers and other system headers, preferably
304 in alphabetical order. (Occasionally one encounters a set of
305 system headers that must be included in a particular order, in
306 which case that order must take precedence.)
308 4. Open vSwitch headers, in alphabetical order. Use "", not <>,
309 to specify Open vSwitch header names.
314 Each header file should start with its license, as described under
315 SOURCE FILES above, followed by a "header guard" to make the header
316 file idempotent, like so:
323 #endif /* netdev.h */
325 Header files should be self-contained; that is, they should #include
326 whatever additional headers are required, without requiring the client
327 to #include them for it.
329 Don't define the members of a struct or union in a header file,
330 unless client code is actually intended to access them directly or if
331 the definition is otherwise actually needed (e.g. inline functions
332 defined in the header need them).
334 Similarly, don't #include a header file just for the declaration of
335 a struct or union tag (e.g. just for "struct <name>;"). Just declare
336 the tag yourself. This reduces the number of header file
342 Use typedefs sparingly. Code is clearer if the actual type is
343 visible at the point of declaration. Do not, in general, declare a
344 typedef for a struct, union, or enum. Do not declare a typedef for a
345 pointer type, because this can be very confusing to the reader.
347 A function type is a good use for a typedef because it can clarify
348 code. The type should be a function type, not a pointer-to-function
349 type. That way, the typedef name can be used to declare function
350 prototypes. (It cannot be used for function definitions, because that
351 is explicitly prohibited by C89 and C99.)
353 You may assume that "char" is exactly 8 bits and that "int" and
354 "long" are at least 32 bits.
356 Don't assume that "long" is big enough to hold a pointer. If you
357 need to cast a pointer to an integer, use "intptr_t" or "uintptr_t"
360 Use the int<N>_t and uint<N>_t types from <stdint.h> for exact-width
361 integer types. Use the PRId<N>, PRIu<N>, and PRIx<N> macros from
362 <inttypes.h> for formatting them with printf() and related functions.
364 Use %zu to format size_t with printf().
366 Use bit-fields sparingly. Do not use bit-fields for layout of
367 network protocol fields or in other circumstances where the exact
370 Declare bit-fields to be type "unsigned int" or "signed int". Do
371 *not* declare bit-fields of type "int": C89 allows these to be either
372 signed or unsigned according to the compiler's whim. (A 1-bit
373 bit-field of type "int" may have a range of -1...0!) Do not declare
374 bit-fields of type _Bool or enum or any other type, because these are
377 Try to order structure members such that they pack well on a system
378 with 2-byte "short", 4-byte "int", and 4- or 8-byte "long" and pointer
379 types. Prefer clear organization over size optimization unless you
380 are convinced there is a size or speed benefit.
382 Pointer declarators bind to the variable name, not the type name.
383 Write "int *x", not "int* x" and definitely not "int * x".
388 Put one space on each side of infix binary and ternary operators:
401 = += -= *= /= %= &= ^= |= <<= >>=
403 Avoid comma operators.
405 Do not put any white space around postfix, prefix, or grouping
411 Exception 1: Put a space after (but not before) the "sizeof" keyword.
412 Exception 2: Put a space between the () used in a cast and the
413 expression whose type is cast: (void *) 0.
415 Break long lines before the ternary operators ? and :, rather than
418 return (out_port != VIGP_CONTROL_PATH
419 ? alpheus_output_port(dp, skb, out_port)
420 : alpheus_output_control(dp, skb, fwd_save_skb(skb),
424 Do not parenthesize the operands of && and || unless operator
425 precedence makes it necessary, or unless the operands are themselves
426 expressions that use && and ||. Thus:
428 if (!isdigit((unsigned char)s[0])
429 || !isdigit((unsigned char)s[1])
430 || !isdigit((unsigned char)s[2])) {
431 printf("string %s does not start with 3-digit code\n", s);
436 if (rule && (!best || rule->priority > best->priority)) {
440 Do parenthesize a subexpression that must be split across more than
443 *idxp = ((l1_idx << PORT_ARRAY_L1_SHIFT)
444 | (l2_idx << PORT_ARRAY_L2_SHIFT)
445 | (l3_idx << PORT_ARRAY_L3_SHIFT));
447 Try to avoid casts. Don't cast the return value of malloc().
449 The "sizeof" operator is unique among C operators in that it accepts
450 two very different kinds of operands: an expression or a type. In
451 general, prefer to specify an expression, e.g. "int *x =
452 xmalloc(sizeof *x);". When the operand of sizeof is an expression,
453 there is no need to parenthesize that operand, and please don't.
455 Use the ARRAY_SIZE macro from lib/util.h to calculate the number of
456 elements in an array.
458 When using a relational operator like "<" or "==", put an expression
459 or variable argument on the left and a constant argument on the
460 right, e.g. "x == 0", *not* "0 == x".
465 Put one blank line between top-level definitions of functions and
471 Try to avoid using GCC extensions where possible.
473 Some C99 extensions are OK:
475 * Flexible array members (e.g. struct { int foo[]; }).
477 * "static inline" functions (but no other forms of "inline", for
478 which GCC and C99 have differing interpretations).
482 * <stdint.h> and <inttypes.h>.
484 * bool and <stdbool.h>, but don't assume that bool or _Bool can
485 only take on the values 0 or 1, because this behavior can't be
486 simulated on C89 compilers.
488 Don't use other C99 extensions, and especially:
490 * Don't use // comments.
492 * Don't use designated initializers (e.g. don't write "struct foo
493 foo = {.a = 1};" or "int a[] = {[2] = 5};").
495 * Don't mix declarations and code within a block.
497 * Don't use declarations in iteration statements (e.g. don't write
498 "for (int i = 0; i < 10; i++)").
500 * Don't put a trailing comma in an enum declaration (e.g. don't
501 write "enum { x = 1, };").