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
  20 Declaration Order
  21 -----------------
  22
  23 Here is the order in which code should be laid out in a file:
  24
  25  - commented program name and one-line description
  26  - commented author name and email address(es)
  27  - commented GPL boilerplate
  28  - commented longer description / notes for the program (if needed)
  29  - #includes and #defines
  30  - const and global variables
  31  - function declarations (if necessary)
  32  - function implementations
  33
  34
  35
  36 Whitespace and Formatting
  37 -------------------------
  38
  39 This is everybody's favorite flame topic so let's get it out of the way right
  40 up front.
  41
  42
  43 Tabs vs. Spaces in Line Indentation
  44 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  45
  46 The preference in Busybox is to indent lines with tabs. Do not indent lines
  47 with spaces and do not indents lines using a mixture of tabs and spaces. (The
  48 indentation style in the Apache and Postfix source does this sort of thing:
  49 \s\s\s\sif (expr) {\n\tstmt; --ick.) The only exception to this rule is
  50 multi-line comments that use an asterisk at the beginning of each line, i.e.:
  51
  52         /t/*
  53         /t * This is a block comment.
  54         /t * Note that it has multiple lines
  55         /t * and that the beginning of each line has a tab plus a space
  56         /t * except for the opening '/*' line where the slash
  57         /t * is used instead of a space.
  58         /t */
  59
  60 Furthermore, The preference is that tabs be set to display at four spaces
  61 wide, but the beauty of using only tabs (and not spaces) at the beginning of
  62 lines is that you can set your editor to display tabs at *whatever* number of
  63 spaces is desired and the code will still look fine.
  64
  65
  66 Operator Spacing
  67 ~~~~~~~~~~~~~~~~
  68
  69 Put spaces between terms and operators. Example:
  70
  71         Don't do this:
  72
  73                 for(i=0;i<num_items;i++){
  74
  75         Do this instead:
  76
  77                 for (i = 0; i < num_items; i++) {
  78
  79         While it extends the line a bit longer, the spaced version is more
  80         readable. An allowable exception to this rule is the situation where
  81         excluding the spacing makes it more obvious that we are dealing with a
  82         single term (even if it is a compound term) such as:
  83
  84                 if (str[idx] == '/' && str[idx-1] != '\\')
  85
  86         or
  87
  88                 if ((argc-1) - (optind+1) > 0)
  89
  90
  91 Bracket Spacing
  92 ~~~~~~~~~~~~~~~
  93
  94 If an opening bracket starts a function, it should be on the
  95 next line with no spacing before it. However, if a bracket follows an opening
  96 control block, it should be on the same line with a single space (not a tab)
  97 between it and the opening control block statement. Examples:
  98
  99         Don't do this:
 100
 101                 while (!done)
 102                 {
 103
 104                 do
 105                 {
 106
 107         Don't do this either:
 108
 109                 while (!done){
 110
 111                 do{
 112
 113         And for heaven's sake, don't do this:
 114
 115                 while (!done)
 116                   {
 117
 118                 do
 119                   {
 120
 121         Do this instead:
 122
 123                 while (!done) {
 124
 125                 do {
 126
 127
 128 Spacing around Parentheses
 129 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 130
 131 Put a space between C keywords and left parens, but not between
 132 function names and the left paren that starts it's parameter list (whether it
 133 is being declared or called). Examples:
 134
 135         Don't do this:
 136
 137                 while(foo) {
 138                 for(i = 0; i < n; i++) {
 139
 140         Do this instead:
 141
 142                 while (foo) {
 143                 for (i = 0; i < n; i++) {
 144
 145         But do functions like this:
 146
 147                 static int my_func(int foo, char bar)
 148                 ...
 149                 baz = my_func(1, 2);
 150
 151 Also, don't put a space between the left paren and the first term, nor between
 152 the last arg and the right paren.
 153
 154         Don't do this:
 155
 156                 if ( x < 1 )
 157                 strcmp( thisstr, thatstr )
 158
 159         Do this instead:
 160
 161                 if (x < 1)
 162                 strcmp(thisstr, thatstr)
 163
 164
 165 Cuddled Elses
 166 ~~~~~~~~~~~~~
 167
 168 Also, please "cuddle" your else statements by putting the else keyword on the
 169 same line after the right bracket that closes an 'if' statement.
 170
 171         Don't do this:
 172
 173         if (foo) {
 174                 stmt;
 175         }
 176         else {
 177                 stmt;
 178         }
 179
 180         Do this instead:
 181
 182         if (foo) {
 183                 stmt;
 184         } else {
 185                 stmt;
 186         }
 187
 188 The exception to this rule is if you want to include a comment before the else
 189 block. Example:
 190
 191         if (foo) {
 192                 stmts...
 193         }
 194         /* otherwise, we're just kidding ourselves, so re-frob the input */
 195         else {
 196                 other_stmts...
 197         }
 198
 199
 200
 201
 202 Variable and Function Names
 203 ---------------------------
 204
 205 Use the K&R style with names in all lower-case and underscores occasionally
 206 used to separate words (e.g., "variable_name" and "numchars" are both
 207 acceptable). Using underscores makes variable and function names more readable
 208 because it looks like whitespace; using lower-case is easy on the eyes.
 209
 210         Frowned upon:
 211
 212                 hitList
 213                 TotalChars
 214                 szFileName
 215                 pf_Nfol_TriState
 216
 217         Preferred:
 218
 219                 hit_list
 220                 total_chars
 221                 file_name
 222                 sensible_name
 223
 224 Exceptions:
 225
 226  - Enums, macros, and constant variables should all be in upper-case with
 227    words optionally seperatedy by underscores (i.e. FIFOTYPE, ISBLKDEV()).
 228
 229  - Nobody is going to get mad at you for using 'pvar' as the name of a
 230    variable that is a pointer to 'var'.
 231
 232 Note: The Busybox codebase is very much a mixture of code gathered from a
 233 variety of sources. This explains why the current codebase contains such a
 234 hodge-podge of different naming styles (Java, Pascal, K&R, just-plain-weird,
 235 etc.). The K&R guideline explained above should therefore be used on new files
 236 that are added to the repository. Furthermore, the maintainer of an existing
 237 file that uses alternate naming conventions should -- at his own convenience
 238 -- convert those names over to K&R style; converting variable names is a very
 239 low priority task. Perhaps in the future we will include some magical Perl
 240 script that can go through and convert variable names, left as an exercise for
 241 the reader for now.
 242
 243 For the time being, if you want to do a search-and-replace of a variable name
 244 in different files, do the following in the busybox directory:
 245
 246         $ perl -pi -e 's/\bOldVar\b/new_var/g' *.[ch]
 247
 248
 249
 250 Avoid The Preprocessor
 251 ----------------------
 252
 253 At best, the preprocessor is a necessary evil, helping us account for platform
 254 and architecture differences. Using the preprocessor unnecessarily is just
 255 plain evil.
 256
 257
 258 The Folly of #define
 259 ~~~~~~~~~~~~~~~~~~~~
 260
 261 Use 'const <type> var' for declaring constants.
 262
 263         Don't do this:
 264
 265                 #define var 80
 266
 267         Do this instead, when the variable is in a header file and will be used in
 268         several source files:
 269
 270                 const int var = 80;
 271
 272         Or do this when the variable is used only in a single source file:
 273
 274                 static const int var = 80;
 275
 276 Declaring variables as '[static] const' gives variables an actual type and
 277 makes the compiler do type checking for you; the preprocessor does _no_ type
 278 checking whatsoever, making it much more error prone. Declaring variables with
 279 '[static] const' also makes debugging programs much easier since the value of
 280 the variable can be easily queried and displayed.
 281
 282
 283 The Folly of Macros
 284 ~~~~~~~~~~~~~~~~~~~
 285
 286 Use 'static inline' instead of a macro.
 287
 288         Don't do this:
 289
 290                 #define mini_func(param1, param2) (param1 << param2)
 291
 292         Do this instead:
 293
 294                 static inline int mini_func(int param1, param2)
 295                 {
 296                         return (param1 << param2);
 297                 }
 298
 299 Static inline functions are greatly preferred over macros. They provide type
 300 safety, have no length limitations, no formatting limitations, and under gcc
 301 they are as cheap as macros. Besides, really long macros with backslashes at
 302 the end of each line are ugly as sin.
 303
 304
 305 The Folly of #ifdef
 306 ~~~~~~~~~~~~~~~~~~~
 307
 308 Code cluttered with ifdefs is difficult to read and maintain. Don't do it.
 309 Instead, put your ifdefs in a header, and conditionally define 'static inline'
 310 functions, (or *maybe* macros), which are used in the code.
 311
 312         Don't do this:
 313
 314                 ret = my_func(bar, baz);
 315                 if (!ret)
 316                         return -1;
 317                 #ifdef BB_FEATURE_FUNKY
 318                         maybe_do_funky_stuff(bar, baz);
 319                 #endif
 320
 321         Do this instead:
 322
 323         (in .h header file)
 324
 325                 #ifdef BB_FEATURE_FUNKY
 326                 static inline void maybe_do_funky_stuff (int bar, int baz)
 327                 {
 328                         /* lotsa code in here */
 329                 }
 330                 #else
 331                 static inline void maybe_do_funky_stuff (int bar, int baz) {}
 332                 #endif
 333
 334         (in the .c source file)
 335
 336                 ret = my_func(bar, baz);
 337                 if (!ret)
 338                         return -1;
 339                 maybe_do_funky_stuff(bar, baz);
 340
 341 The great thing about this approach is that the compiler will optimize away
 342 the "no-op" case (the empty function) when the feature is turned off.
 343
 344 Note also the use of the word 'maybe' in the function name to indicate
 345 conditional execution.
 346
 347
 348
 349 Notes on Strings
 350 ----------------
 351
 352 Strings in C can get a little thorny. Here's some guidelines for dealing with
 353 strings in Busybox. (There is surely more that could be added to this
 354 section.)
 355
 356
 357 String Files
 358 ~~~~~~~~~~~~
 359
 360 Put all help/usage messages in usage.c. Put other strings in messages.c.
 361 Putting these strings into their own file is a calculated decision designed to
 362 confine spelling errors to a single place and aid internationalization
 363 efforts, if needed. (Side Note: we might want to use a single file - maybe
 364 called 'strings.c' - instead of two, food for thought).
 365
 366
 367 Testing String Equivalence
 368 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 369
 370 There's a right way and a wrong way to test for sting equivalence with
 371 strcmp():
 372
 373         The wrong way:
 374
 375                 if (!strcmp(string, "foo")) {
 376                         ...
 377
 378         The right way:
 379
 380                 if (strcmp(string, "foo") == 0){
 381                         ...
 382
 383 The use of the "equals" (==) operator in the latter example makes it much more
 384 obvious that you are testing for equivalence. The former example with the
 385 "not" (!) operator makes it look like you are testing for an error. In a more
 386 perfect world, we would have a streq() function in the string library, but
 387 that ain't the world we're living in.
 388
 389
 390 Avoid Dangerous String Functions
 391 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 392
 393 Unfortunately, the way C handles strings makes them prone to overruns when
 394 certain library functions are (mis)used. The following table  offers a summary
 395 of some of the more notorious troublemakers:
 396
 397 function     overflows         preferred
 398 ----------------------------------------
 399 strcpy       dest string       strncpy
 400 strcat       dest string       strncat
 401 gets         string it gets    fgets
 402 getwd        buf string        getcwd
 403 [v]sprintf   str buffer        [v]snprintf
 404 realpath     path buffer       use with pathconf
 405 [vf]scanf    its arguments     just avoid it
 406
 407
 408 The above is by no means a complete list. Be careful out there.
 409
 410
 411
 412 Avoid Big Static Buffers
 413 ------------------------
 414
 415 First, some background to put this discussion in context: Static buffers look
 416 like this in code:
 417
 418         /* in a .c file outside any functions */
 419         static char *buffer[BUFSIZ]; /* happily used by any function in this file,
 420                                         but ick! big! */
 421
 422 The problem with these is that any time any busybox app is run, you pay a
 423 memory penalty for this buffer, even if the applet that uses said buffer is
 424 not run. This can be fixed, thusly:
 425
 426         static char *buffer;
 427         ...
 428         other_func()
 429         {
 430                 strcpy(buffer, lotsa_chars); /* happily uses global *buffer */
 431         ...
 432         foo_main()
 433         {
 434                 buffer = xmalloc(sizeof(char)*BUFSIZ);
 435         ...
 436
 437 However, this approach trades bss segment for text segment. Rather than
 438 mallocing the buffers (and thus growing the text size), buffers can be
 439 declared on the stack in the *_main() function and made available globally by
 440 assigning them to a global pointer thusly:
 441
 442         static char *pbuffer;
 443         ...
 444         other_func()
 445         {
 446                 strcpy(pbuffer, lotsa_chars); /* happily uses global *pbuffer */
 447         ...
 448         foo_main()
 449         {
 450                 char *buffer[BUFSIZ]; /* declared locally, on stack */
 451                 pbuffer = buffer;     /* but available globally */
 452         ...
 453
 454 This last approach has some advantages (low code size, space not used until
 455 it's needed), but can be a problem in some low resource machines that have
 456 very limited stack space (e.g., uCLinux).
 457
 458 A macro is declared in busybox.h that implements compile-time selection
 459 between xmalloc() and stack creation, so you can code the line in question as
 460
 461                 RESERVE_BB_BUFFER(buffer, BUFSIZ);
 462
 463 and the right thing will happen, based on your configuration.
 464
 465
 466
 467 Miscellaneous Coding Guidelines
 468 -------------------------------
 469
 470 The following are important items that don't fit into any of the above
 471 sections.
 472
 473
 474 Model Busybox Applets After GNU Counterparts
 475 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 476
 477 When in doubt about the proper behavior of a Busybox program (output,
 478 formatting, options, etc.), model it after the equivalent GNU program.
 479 Doesn't matter how that program behaves on some other flavor of *NIX; doesn't
 480 matter what the POSIX standard says or doesn't say, just model Busybox
 481 programs after their GNU counterparts and nobody has to get hurt.
 482
 483 The only time we deviate from emulating the GNU behavior is when:
 484
 485         - We are deliberately not supporting a feature (such as a command line
 486           switch)
 487         - Emulating the GNU behavior is prohibitively expensive (lots more code
 488           would be required, lots more memory would be used, etc.)
 489         - The difference is minor or cosmetic
 490
 491 A note on the 'cosmetic' case: Output differences might be considered
 492 cosmetic, but if the output is significant enough to break other scripts that
 493 use the output, it should really be fixed.
 494
 495
 496 Scope
 497 ~~~~~
 498
 499 If a const variable is used only in a single source file, put it in the source
 500 file and not in a header file. Likewise, if a const variable is used in only
 501 one function, do not make it global to the file. Instead, declare it inside
 502 the function body. Bottom line: Make a conscious effort to limit declarations
 503 to the smallest scope possible.
 504
 505 Inside applet files, all functions should be declared static so as to keep the
 506 global name space clean. The only exception to this rule is the "applet_main"
 507 function which must be declared extern.
 508
 509 If you write a function that performs a task that could be useful outside the
 510 immediate file, turn it into a general-purpose function with no ties to any
 511 applet and put it in the utility.c file instead.
 512
 513
 514 Brackets Are Your Friends
 515 ~~~~~~~~~~~~~~~~~~~~~~~~~
 516
 517 Please use brackets on all if and else statements, even if it is only one
 518 line. Example:
 519
 520         Don't do this:
 521
 522                 if (foo)
 523                         stmt1;
 524                 stmt2
 525                 stmt3;
 526
 527         Do this instead:
 528
 529                 if (foo) {
 530                         stmt1;
 531                 }
 532                 stmt2
 533                 stmt3;
 534
 535 The "bracketless" approach is error prone because someday you might add a line
 536 like this:
 537
 538                 if (foo)
 539                         stmt1;
 540                         new_line();
 541                 stmt2
 542                 stmt3;
 543
 544 And the resulting behavior of your program would totally bewilder you. (Don't
 545 laugh, it happens to us all.) Remember folks, this is C, not Python.
 546
 547
 548 Function Declarations
 549 ~~~~~~~~~~~~~~~~~~~~~
 550
 551 Do not use old-style function declarations that declare variable types between
 552 the parameter list and opening bracket. Example:
 553
 554         Don't do this:
 555
 556                 int foo(parm1, parm2)
 557                         char parm1;
 558                         float parm2;
 559                 {
 560                         ....
 561
 562         Do this instead:
 563
 564                 int foo(char parm1, float parm2)
 565                 {
 566                         ....
 567
 568 The only time you would ever need to use the old declaration syntax is to
 569 support ancient, antediluvian compilers. To our good fortune, we have access
 570 to more modern compilers and the old declaration syntax is neither necessary
 571 nor desired.
 572
 573
 574 Emphasizing Logical Blocks
 575 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 576
 577 Organization and readability are improved by putting extra newlines around
 578 blocks of code that perform a single task. These are typically blocks that
 579 begin with a C keyword, but not always.
 580
 581 Furthermore, you should put a single comment (not necessarily one line, just
 582 one comment) before the block, rather than commenting each and every line.
 583 There is an optimal ammount of commenting that a program can have; you can
 584 comment too much as well as too little.
 585
 586 A picture is really worth a thousand words here, so here is an example that
 587 illustrates emphasizing logical blocks:
 588
 589         while (line = get_line_from_file(fp)) {
 590
 591                 /* eat the newline, if any */
 592                 if (line[strlen(line)-1] == '\n') {
 593                         line[strlen(line)-1] = '\0';
 594                 }
 595
 596                 /* ignore blank lines */
 597                 if (strlen(file_to_act_on) == 0) {
 598                         continue;
 599                 }
 600
 601                 /* if the search string is in this line, print it,
 602                  * unless we were told to be quiet */
 603                 if (strstr(line, search) && !be_quiet) {
 604                         puts(line);
 605                 }
 606
 607                 /* clean up */
 608                 free(line);
 609         }
 610
 611
 612 Testing Guidelines
 613 ~~~~~~~~~~~~~~~~~~
 614
 615 It's considered good form to test your new feature before you submit a patch
 616 to the mailing list, and especially before you commit a change to CVS. Here
 617 are some guildlines on testing your changes.
 618
 619  - Always test busybox applets against GNU counterparts and make sure the
 620    behavior / output is identical between the two.
 621
 622  - Try several different permutations and combinations of the features you're
 623    adding and make sure they all work. (Make sure one feature does not
 624    interfere with another, etc.)
 625
 626  - Make sure you test compiling against the source both with the feature
 627    turned on and turned off in Config.h and make sure busybox compiles cleanly
 628    both ways.
 629