Try to make a "type-punned pointer" warning go away for somebody on the

[oweals/busybox.git] / docs / style-guide.txt

diff --git a/docs/style-guide.txt b/docs/style-guide.txt
index c71f1e6098d15df8c5115fb2b4622f78c3e6b5fb..ba0cdbaa487e7f6579746c7d6101e9a3d8416bc4 100644 (file)
--- a/docs/style-guide.txt
+++ b/docs/style-guide.txt
@@ -51,13 +51,13 @@ indentation style in the Apache and Postfix source does this sort of thing:
 \s\s\s\sif (expr) {\n\tstmt; --ick.) The only exception to this rule is
 multi-line comments that use an asterisk at the beginning of each line, i.e.:
 
-       /t/*
-       /t * This is a block comment.
-       /t * Note that it has multiple lines
-       /t * and that the beginning of each line has a tab plus a space
-       /t * except for the opening '/*' line where the slash
-       /t * is used instead of a space.
-       /t */
+       \t/*
+       \t * This is a block comment.
+       \t * Note that it has multiple lines
+       \t * and that the beginning of each line has a tab plus a space
+       \t * except for the opening '/*' line where the slash
+       \t * is used instead of a space.
+       \t */
 
 Furthermore, The preference is that tabs be set to display at four spaces
 wide, but the beauty of using only tabs (and not spaces) at the beginning of
@@ -126,6 +126,15 @@ between it and the opening control block statement. Examples:
 
                do {
 
+Exceptions:
+
+ - if you have long logic statements that need to be wrapped, then uncuddling
+   the bracket to improve readability is allowed:
+
+               if (some_really_long_checks && some_other_really_long_checks \
+                   && some_more_really_long_checks)
+               {
+                       do_foo_now;
 
 Spacing around Parentheses
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -252,7 +261,7 @@ files, you can do the following in the busybox directory:
 If you want to convert all the non-K&R vars in your file all at once, follow
 these steps:
 
- - In the busybox directory type 'scripts/mk2knr.pl files-to-convert'. This
+ - In the busybox directory type 'examples/mk2knr.pl files-to-convert'. This
    does not do the actual conversion, rather, it generates a script called
    'convertme.pl' that shows what will be converted, giving you a chance to
    review the changes beforehand.
@@ -266,10 +275,10 @@ these steps:
    conversion.
 
  - Compile and see if everything still works.
- 
+
 Please be aware of changes that have cascading effects into other files. For
 example, if you're changing the name of something in, say utility.c, you
-should probably run 'scripts/mk2knr.pl utility.c' at first, but when you run
+should probably run 'examples/mk2knr.pl utility.c' at first, but when you run
 the 'convertme.pl' script you should run it on _all_ files like so:
 './convertme.pl *.[ch]'.
 
@@ -293,13 +302,13 @@ Use 'const <type> var' for declaring constants.
                #define var 80
 
        Do this instead, when the variable is in a header file and will be used in
-       several source files: 
+       several source files:
 
-               const int var = 80; 
+               const int var = 80;
 
        Or do this when the variable is used only in a single source file:
 
-               static const int var = 80; 
+               static const int var = 80;
 
 Declaring variables as '[static] const' gives variables an actual type and
 makes the compiler do type checking for you; the preprocessor does _no_ type
@@ -336,14 +345,14 @@ The Folly of #ifdef
 Code cluttered with ifdefs is difficult to read and maintain. Don't do it.
 Instead, put your ifdefs at the top of your .c file (or in a header), and
 conditionally define 'static inline' functions, (or *maybe* macros), which are
-used in the code.  
+used in the code.
 
        Don't do this:
 
                ret = my_func(bar, baz);
                if (!ret)
                        return -1;
-               #ifdef BB_FEATURE_FUNKY
+               #ifdef CONFIG_FEATURE_FUNKY
                        maybe_do_funky_stuff(bar, baz);
                #endif
 
@@ -351,7 +360,7 @@ used in the code.
 
        (in .h header file)
 
-               #ifdef BB_FEATURE_FUNKY
+               #ifdef CONFIG_FEATURE_FUNKY
                static inline void maybe_do_funky_stuff (int bar, int baz)
                {
                        /* lotsa code in here */
@@ -445,7 +454,7 @@ First, some background to put this discussion in context: Static buffers look
 like this in code:
 
        /* in a .c file outside any functions */
-       static char *buffer[BUFSIZ]; /* happily used by any function in this file,
+       static char buffer[BUFSIZ]; /* happily used by any function in this file,
                                        but ick! big! */
 
 The problem with these is that any time any busybox app is run, you pay a
@@ -487,7 +496,7 @@ very limited stack space (e.g., uCLinux).
 A macro is declared in busybox.h that implements compile-time selection
 between xmalloc() and stack creation, so you can code the line in question as
 
-               RESERVE_BB_BUFFER(buffer, BUFSIZ);
+               RESERVE_CONFIG_BUFFER(buffer, BUFSIZ);
 
 and the right thing will happen, based on your configuration.
 
@@ -610,7 +619,7 @@ begin with a C keyword, but not always.
 
 Furthermore, you should put a single comment (not necessarily one line, just
 one comment) before the block, rather than commenting each and every line.
-There is an optimal ammount of commenting that a program can have; you can
+There is an optimal amount of commenting that a program can have; you can
 comment too much as well as too little.
 
 A picture is really worth a thousand words here, the following example
@@ -650,7 +659,7 @@ line in the midst of your #includes:
 And a code block similar to the following near the top of your applet_main()
 routine:
 
-    while ((opt = getopt(argc, argv, "abc")) > 0) { 
+    while ((opt = getopt(argc, argv, "abc")) > 0) {
             switch (opt) {
             case 'a':
                 do_a_opt = 1;