Ignore:
Timestamp:
Nov 4, 2007, 3:16:40 AM (16 years ago)
Author:
Bruno Cornec
Message:

Update to busybox 1.7.2

File:
1 edited

Legend:

Unmodified
Added
Removed
  • branches/2.2.5/mindi-busybox/docs/style-guide.txt

    r821 r1765  
    2121-----------------
    2222
    23 Here is the order in which code should be laid out in a file:
     23Here is the preferred order in which code should be laid out in a file:
    2424
    2525 - commented program name and one-line description
     
    5252multi-line comments that use an asterisk at the beginning of each line, i.e.:
    5353
    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 */
     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 */
    6161
    6262Furthermore, The preference is that tabs be set to display at four spaces
     
    127127        do {
    128128
    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         {
     129If you have long logic statements that need to be wrapped, then uncuddling
     130the bracket to improve readability is allowed. Generally, this style makes
     131it easier for reader to notice that 2nd and following lines are still
     132inside '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        ) {
    137138            do_foo_now;
    138139
     
    209210
    210211
     212Labels
     213~~~~~~
     214
     215Labels should start at the beginning of the line, not indented to the block
     216level (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
     226name, but it's not a policy of busybox project to enforce such a minor detail).
     227
     228
    211229
    212230Variable and Function Names
     
    235253
    236254 - Enums, macros, and constant variables are occasionally written in all
    237    upper-case with words optionally seperatedy by underscores (i.e. FIFOTYPE,
     255   upper-case with words optionally seperatedy by underscores (i.e. FIFO_TYPE,
    238256   ISBLKDEV()).
    239257
     
    300318    Don't do this:
    301319
    302         #define var 80
     320        #define CONST 80
    303321
    304322    Do this instead, when the variable is in a header file and will be used in
    305323    several source files:
    306324
    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
     327Although enum may look ugly to some people, it is better for code size.
     328With "const int" compiler may fail to optimize it out and will reserve
     329a real storage in rodata for it! (Hopefully, newer gcc will get better
     330at it...).  With "define", you have slight risk of polluting namespace
     331(#define doesn't allow you to redefine the name in the inner scopes),
     332and complex "define" are evaluated each time they uesd, not once
     333at declarations like enums. Also, the preprocessor does _no_ type checking
     334whatsoever, making it much more error prone.
    318335
    319336
     
    361378    (in .h header file)
    362379
    363         #ifdef CONFIG_FEATURE_FUNKY
    364         static inline void maybe_do_funky_stuff (int bar, int baz)
     380        #if ENABLE_FEATURE_FUNKY
     381        static inline void maybe_do_funky_stuff(int bar, int baz)
    365382        {
    366383            /* lotsa code in here */
    367384        }
    368385        #else
    369         static inline void maybe_do_funky_stuff (int bar, int baz) {}
     386        static inline void maybe_do_funky_stuff(int bar, int baz) {}
    370387        #endif
    371388
     
    433450of some of the more notorious troublemakers:
    434451
    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
     452function     overflows                  preferred
     453-------------------------------------------------
     454strcpy       dest string                safe_strncpy
     455strncpy      may fail to 0-terminate dst safe_strncpy
     456strcat       dest string                strncat
     457gets         string it gets             fgets
     458getwd        buf string                 getcwd
     459[v]sprintf   str buffer                 [v]snprintf
     460realpath     path buffer                use with pathconf
     461[vf]scanf    its arguments              just avoid it
    444462
    445463
     
    451469------------------------
    452470
    453 First, some background to put this discussion in context: Static buffers look
     471First, some background to put this discussion in context: static buffers look
    454472like this in code:
    455473
     
    501519and the right thing will happen, based on your configuration.
    502520
     521Another relatively new trick of similar nature is explained
     522in keep_data_small.txt.
     523
    503524
    504525
     
    528549    - The difference is minor or cosmetic
    529550
    530 A note on the 'cosmetic' case: Output differences might be considered
     551A note on the 'cosmetic' case: output differences might be considered
    531552cosmetic, but if the output is significant enough to break other scripts that
    532553use the output, it should really be fixed.
     
    578599            stmt1;
    579600            new_line();
    580         stmt2
     601        stmt2;
    581602        stmt3;
    582603
     
    620641Furthermore, you should put a single comment (not necessarily one line, just
    621642one comment) before the block, rather than commenting each and every line.
    622 There is an optimal ammount of commenting that a program can have; you can
     643There is an optimal amount of commenting that a program can have; you can
    623644comment too much as well as too little.
    624645
     
    626647illustrates how to emphasize logical blocks:
    627648
    628     while (line = get_line_from_file(fp)) {
     649    while (line = xmalloc_fgets(fp)) {
    629650
    630651        /* eat the newline, if any */
     
    650671~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    651672
    652 If your applet needs to process  command-line switches, please use getopt() to
     673If your applet needs to process command-line switches, please use getopt32() to
    653674do so. Numerous examples can be seen in many of the existing applets, but
    654675basically it boils down to two things: at the top of the .c file, have this
    655 line in the midst of your #includes:
     676line in the midst of your #includes, if you need to parse long options:
    656677
    657678    #include <getopt.h>
     679
     680Then 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    };
    658687
    659688And a code block similar to the following near the top of your applet_main()
    660689routine:
    661690
    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    }
    677705
    678706If your applet takes no options (such as 'init'), there should be a line
     
    684712use getopt, they won't get false positives.
    685713
    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.
     714For more info and examples, examine getopt32.c, tar.c, wget.c etc.
Note: See TracChangeset for help on using the changeset viewer.