docs/style-guide.txt

   1 Busybox Style Guide
   2 ===================
   3
   4 This document describes the coding style conventions used in Busybox. If you
   5 add a new file to Busybox or are editing an existing file, please format your
   6 code according to this style. If you are the maintainer of a file that does
   7 not follow these guidelines, please -- at your own convenience -- modify the
   8 file(s) you maintain to bring them into conformance with this style guide.
   9 Please note that this is a low priority task.
  10
  11 To help you format the whitespace of your programs, an ".indent.pro" file is
  12 included in the main Busybox source directory that contains option flags to
  13 format code as per this style guide. This way you can run GNU indent on your
  14 files by typing 'indent myfile.c myfile.h' and it will magically apply all the
  15 right formatting rules to your file. Please _do_not_ run this on all the files
  16 in the directory, just your own.
  17
  18
  19 Declaration Order
  20 -----------------
  21
  22 Here is the order in which code should be laid out in a file:
  23
  24  - commented author name and email address(es)
  25  - commented GPL boilerplate
  26  - commented description of program
  27  - #includes and #defines
  28  - const and globals variables
  29  - function declarations (if necessary)
  30  - function implementations
  31
  32
  33 Whitespace
  34 ----------
  35
  36 This is everybody's favorite flame topic so let's get it out of the way right
  37 up front.
  38
  39
  40 Tabs vs Spaces in Line Indentation
  41 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  42
  43 The preference in Busybox is to indent lines with tabs. Do not indent lines
  44 with spaces and do not indents lines using a mixture of tabs and spaces. (The
  45 indentation style in the Apache and Postfix source does this sort of thing:
  46 \s\s\s\sif (expr) {\n\tstmt; --ick.) The only exception to this rule is
  47 multi-line comments that use an asterisk at the beginning of each line, i.e.:
  48
  49         /t/*
  50         /t * This is a block comment.
  51         /t * Note that it has multiple lines
  52         /t * and that the beginning of each line has a tab plus a space
  53         /t * except for the opening '/*' line where the slash
  54         /t * is used instead of a space.
  55         /t */
  56
  57 Furthermore, The preference is that tabs be set to display at four spaces
  58 wide, but the beauty of using only tabs (and not spaces) at the beginning of
  59 lines is that you can set your editor to display tabs at *watever* number of
  60 spaces is desired and the code will still look fine.
  61
  62
  63 Operator Spacing
  64 ~~~~~~~~~~~~~~~~
  65
  66 Put spaces between terms and operators. Example:
  67
  68         Don't do this:
  69
  70                 for(i=0;i<num_items;i++){
  71
  72         Do this instead:
  73
  74                 for (i = 0; i < num_items; i++) {
  75
  76         While it extends the line a bit longer, the spaced version is more
  77         readable. An allowable exception to this rule is the situation where
  78         excluding the spacing makes it more obvious that we are dealing with a
  79         single term (even if it is a compund term) such as:
  80
  81                 if (str[idx] == '/' && str[idx-1] != '\\')
  82
  83         or
  84
  85                 if ((argc-1) - (optind+1) > 0)
  86
  87
  88 Bracket Spacing
  89 ~~~~~~~~~~~~~~~
  90
  91 If an opening bracket starts a function, it should be on the
  92 next line with no spacing before it. However, if a bracet follows an opening
  93 control block, it should be on the same line with a single space (not a tab)
  94 between it and the opening control block statment. Examples:
  95
  96         Don't do this:
  97
  98                 while (!done){
  99                 do{
 100
 101         Do this instead:
 102
 103                 while (!done) {
 104                 do {
 105
 106
 107 Paren Spacing
 108 ~~~~~~~~~~~~~
 109
 110 Put a space between C keywords and left parens, but not between
 111 function names and the left paren that starts it's parameter list (whether it
 112 is being declared or called). Examples:
 113
 114         Don't do this:
 115
 116                 while(foo) {
 117                 for(i = 0; i < n; i++) {
 118
 119         Do this instead:
 120
 121                 while (foo) {
 122                 for (i = 0; i < n; i++) {
 123
 124         Do functions like this:
 125
 126                 static int my_func(int foo, char bar)
 127                 ...
 128                 baz = my_func(1, 2);
 129
 130
 131 Cuddled Elses
 132 ~~~~~~~~~~~~~
 133
 134 Also, please "cuddle" your else statments by putting the else keyword on the
 135 same line after the right bracket that closes an 'if' statment.
 136
 137         Don't do this:
 138
 139         if (foo) {
 140                 stmt;
 141         }
 142         else {
 143                 stmt;
 144         }
 145
 146         Do this instead:
 147
 148         if (foo) {
 149                 stmt;
 150         } else {
 151                 stmt;
 152         }
 153
 154
 155 Variable and Function Names
 156 ---------------------------
 157
 158 Use the K&R style with names in all lower-case and underscores occasionally
 159 used to seperate words (e.g. "variable_name" and "numchars" are both
 160 acceptable). Using underscores makes variable and function names more readable
 161 because it looks like whitespace; using lower-case is easy on the eyes.
 162
 163 Note: The Busybox codebase is very much a mixture of code gathered from a
 164 variety of locations. This explains why the current codebase contains such a
 165 plethora of different naming styles (Java, Pascal, K&R, just-plain-weird,
 166 etc.). The K&R guideline explained above should therefore be used on new files
 167 that are added to the repository. Furthermore, the maintainer of an existing
 168 file that uses alternate naming conventions should -- at his own convenience
 169 -- convert those names over to K&R style; converting variable names is a very
 170 low priority task. Perhaps in the future we will include some magical Perl
 171 script that can go through and convert files--left as an exersize to the
 172 reader.
 173
 174
 175 Tip and Pointers
 176 ----------------
 177
 178 The following are simple coding guidelines that should be followed:
 179
 180  - When in doubt about the propper behavior of a busybox program (output,
 181    formatting, options, etc.), model it after the equivalent GNU program.
 182    Doesn't matter how that program behaves on some other flavor of *NIX;
 183    doesn't matter what the POSIX standard says or doesn't say, just model
 184    busybox programs after their GNU counterparts and nobody has to get hurt.
 185
 186  - Don't use a '#define var 80' when you can use 'static const int var 80'
 187    instead. This makes the compiler do typechecking for you (rather than
 188    relying on the more error-prone preprocessor) and it makes debugging
 189    programs much easier since the value of the variable can be easily queried.
 190
 191  - If a const variable is used in only one function, do not make it global to
 192    the file. Instead, declare it inside the function body.
 193
 194  - Inside applet files, all functions should be declared static so as to keep
 195    the global namespace clean. The only exception to this rule is the
 196    "applet_main" function which must be declared extern.
 197
 198  - If you write a function that performs a task that could be useful outside
 199    the immediate file, turn it into a general-purpose function with no ties to
 200    any applet and put it in the utility.c file instead.
 201
 202  - Put all help/usage messages in usage.c. Put other strings in messages.c
 203    (Side Note: we might want to use a single file instead of two, food for
 204    thought).
 205
 206  - There's a right way and a wrong way to test for sting equivalence with
 207    strcmp:
 208
 209         The wrong way:
 210
 211         if (!strcmp(string, "foo")) {
 212                 ...
 213
 214         The right way:
 215
 216         if (strcmp(string, "foo") == 0){
 217                 ...
 218
 219         The use of the "equals" (==) operator in the latter example makes it much
 220         more obvious that you are testing for equivalence. The former example with
 221         the "not" (!) operator makes it look like you are testing for an error.
 222
 223  - Do not use old-style function declarations that declare variable types
 224    between the parameter list and opening bracket. Example:
 225
 226         Don't do this:
 227
 228                 int foo(parm1, parm2)
 229                         char parm1;
 230                         float parm2;
 231                 {
 232                         ....
 233
 234         Do this instead:
 235
 236                 int foo(char parm1, float parm2)
 237                 {
 238                         ....
 239
 240  - Please use brackets on all if and else statements, even if it is only one
 241    line. Example:
 242
 243         Don't do this:
 244
 245                 if (foo)
 246                         stmt;
 247                 else
 248                         stmt;
 249
 250         Do this instead:
 251
 252                 if (foo) {
 253                         stmt;
 254                 } else {
 255                         stmt;
 256                 }
 257
 258         The "bracketless" approach is error prone because someday you might add a
 259         line like this:
 260
 261                 if (foo)
 262                         stmt;
 263                         new_line();
 264                 else
 265                         stmt;
 266
 267         And the resulting behavior of your program would totally bewilder you.
 268         (Don't laugh, it happens to us all.) Remember folks, this is C, not
 269         Python.