Changeset 1765 in MondoRescue for branches/2.2.5/mindi-busybox/docs/style-guide.txt
- Timestamp:
- Nov 4, 2007, 3:16:40 AM (16 years ago)
- File:
-
- 1 edited
Legend:
- Unmodified
- Added
- Removed
-
branches/2.2.5/mindi-busybox/docs/style-guide.txt
r821 r1765 21 21 ----------------- 22 22 23 Here is the order in which code should be laid out in a file:23 Here is the preferred order in which code should be laid out in a file: 24 24 25 25 - commented program name and one-line description … … 52 52 multi-line comments that use an asterisk at the beginning of each line, i.e.: 53 53 54 /t/*55 /t * This is a block comment.56 /t * Note that it has multiple lines57 /t * and that the beginning of each line has a tab plus a space58 /t * except for the opening '/*' line where the slash59 /t * is used instead of a space.60 /t */54 \t/* 55 \t * This is a block comment. 56 \t * Note that it has multiple lines 57 \t * and that the beginning of each line has a tab plus a space 58 \t * except for the opening '/*' line where the slash 59 \t * is used instead of a space. 60 \t */ 61 61 62 62 Furthermore, The preference is that tabs be set to display at four spaces … … 127 127 do { 128 128 129 Exceptions: 130 131 - if you have long logic statements that need to be wrapped, then uncuddling 132 the bracket to improve readability is allowed: 133 134 if (some_really_long_checks && some_other_really_long_checks \ 135 && some_more_really_long_checks) 136 { 129 If you have long logic statements that need to be wrapped, then uncuddling 130 the bracket to improve readability is allowed. Generally, this style makes 131 it easier for reader to notice that 2nd and following lines are still 132 inside 'if': 133 134 if (some_really_long_checks && some_other_really_long_checks 135 && some_more_really_long_checks 136 && even_more_of_long_checks 137 ) { 137 138 do_foo_now; 138 139 … … 209 210 210 211 212 Labels 213 ~~~~~~ 214 215 Labels should start at the beginning of the line, not indented to the block 216 level (because they do not "belong" to block scope, only to whole function). 217 218 if (foo) { 219 stmt; 220 label: 221 stmt2; 222 stmt; 223 } 224 225 (Putting label at position 1 prevents diff -p from confusing label for function 226 name, but it's not a policy of busybox project to enforce such a minor detail). 227 228 211 229 212 230 Variable and Function Names … … 235 253 236 254 - Enums, macros, and constant variables are occasionally written in all 237 upper-case with words optionally seperatedy by underscores (i.e. FIFO TYPE,255 upper-case with words optionally seperatedy by underscores (i.e. FIFO_TYPE, 238 256 ISBLKDEV()). 239 257 … … 300 318 Don't do this: 301 319 302 #define var80320 #define CONST 80 303 321 304 322 Do this instead, when the variable is in a header file and will be used in 305 323 several source files: 306 324 307 const int var = 80; 308 309 Or do this when the variable is used only in a single source file: 310 311 static const int var = 80; 312 313 Declaring variables as '[static] const' gives variables an actual type and 314 makes the compiler do type checking for you; the preprocessor does _no_ type 315 checking whatsoever, making it much more error prone. Declaring variables with 316 '[static] const' also makes debugging programs much easier since the value of 317 the variable can be easily queried and displayed. 325 enum { CONST = 80 }; 326 327 Although enum may look ugly to some people, it is better for code size. 328 With "const int" compiler may fail to optimize it out and will reserve 329 a real storage in rodata for it! (Hopefully, newer gcc will get better 330 at it...). With "define", you have slight risk of polluting namespace 331 (#define doesn't allow you to redefine the name in the inner scopes), 332 and complex "define" are evaluated each time they uesd, not once 333 at declarations like enums. Also, the preprocessor does _no_ type checking 334 whatsoever, making it much more error prone. 318 335 319 336 … … 361 378 (in .h header file) 362 379 363 #if def CONFIG_FEATURE_FUNKY364 static inline void maybe_do_funky_stuff 380 #if ENABLE_FEATURE_FUNKY 381 static inline void maybe_do_funky_stuff(int bar, int baz) 365 382 { 366 383 /* lotsa code in here */ 367 384 } 368 385 #else 369 static inline void maybe_do_funky_stuff 386 static inline void maybe_do_funky_stuff(int bar, int baz) {} 370 387 #endif 371 388 … … 433 450 of some of the more notorious troublemakers: 434 451 435 function overflows preferred 436 ---------------------------------------- 437 strcpy dest string strncpy 438 strcat dest string strncat 439 gets string it gets fgets 440 getwd buf string getcwd 441 [v]sprintf str buffer [v]snprintf 442 realpath path buffer use with pathconf 443 [vf]scanf its arguments just avoid it 452 function overflows preferred 453 ------------------------------------------------- 454 strcpy dest string safe_strncpy 455 strncpy may fail to 0-terminate dst safe_strncpy 456 strcat dest string strncat 457 gets string it gets fgets 458 getwd buf string getcwd 459 [v]sprintf str buffer [v]snprintf 460 realpath path buffer use with pathconf 461 [vf]scanf its arguments just avoid it 444 462 445 463 … … 451 469 ------------------------ 452 470 453 First, some background to put this discussion in context: Static buffers look471 First, some background to put this discussion in context: static buffers look 454 472 like this in code: 455 473 … … 501 519 and the right thing will happen, based on your configuration. 502 520 521 Another relatively new trick of similar nature is explained 522 in keep_data_small.txt. 523 503 524 504 525 … … 528 549 - The difference is minor or cosmetic 529 550 530 A note on the 'cosmetic' case: Output differences might be considered551 A note on the 'cosmetic' case: output differences might be considered 531 552 cosmetic, but if the output is significant enough to break other scripts that 532 553 use the output, it should really be fixed. … … 578 599 stmt1; 579 600 new_line(); 580 stmt2 601 stmt2; 581 602 stmt3; 582 603 … … 620 641 Furthermore, you should put a single comment (not necessarily one line, just 621 642 one comment) before the block, rather than commenting each and every line. 622 There is an optimal am mount of commenting that a program can have; you can643 There is an optimal amount of commenting that a program can have; you can 623 644 comment too much as well as too little. 624 645 … … 626 647 illustrates how to emphasize logical blocks: 627 648 628 while (line = get_line_from_file(fp)) {649 while (line = xmalloc_fgets(fp)) { 629 650 630 651 /* eat the newline, if any */ … … 650 671 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 651 672 652 If your applet needs to process command-line switches, please use getopt() to673 If your applet needs to process command-line switches, please use getopt32() to 653 674 do so. Numerous examples can be seen in many of the existing applets, but 654 675 basically it boils down to two things: at the top of the .c file, have this 655 line in the midst of your #includes :676 line in the midst of your #includes, if you need to parse long options: 656 677 657 678 #include <getopt.h> 679 680 Then have long options defined: 681 682 static const struct option <applet>_long_options[] = { 683 { "list", 0, NULL, 't' }, 684 { "extract", 0, NULL, 'x' }, 685 { NULL, 0, NULL, 0 } 686 }; 658 687 659 688 And a code block similar to the following near the top of your applet_main() 660 689 routine: 661 690 662 while ((opt = getopt(argc, argv, "abc")) > 0) { 663 switch (opt) { 664 case 'a': 665 do_a_opt = 1; 666 break; 667 case 'b': 668 do_b_opt = 1; 669 break; 670 case 'c': 671 do_c_opt = 1; 672 break; 673 default: 674 show_usage(); /* in utility.c */ 675 } 676 } 691 char *str_b; 692 693 opt_complementary = "cryptic_string"; 694 applet_long_options = <applet>_long_options; /* if you have them */ 695 opt = getopt32(argc, argv, "ab:c", &str_b); 696 if (opt & 1) { 697 handle_option_a(); 698 } 699 if (opt & 2) { 700 handle_option_b(str_b); 701 } 702 if (opt & 4) { 703 handle_option_c(); 704 } 677 705 678 706 If your applet takes no options (such as 'init'), there should be a line … … 684 712 use getopt, they won't get false positives. 685 713 686 Additional Note: Do not use the getopt_long library function and do not try to 687 hand-roll your own long option parsing. Busybox applets should only support 688 short options. Explanations and examples of the short options should be 689 documented in usage.h. 714 For more info and examples, examine getopt32.c, tar.c, wget.c etc.
Note:
See TracChangeset
for help on using the changeset viewer.