diff options
| -rw-r--r-- | .indent.pro | 33 | ||||
| -rw-r--r-- | docs/style-guide.txt | 224 |
2 files changed, 257 insertions, 0 deletions
diff --git a/.indent.pro b/.indent.pro new file mode 100644 index 000000000..492ecf1c7 --- /dev/null +++ b/.indent.pro @@ -0,0 +1,33 @@ +--blank-lines-after-declarations +--blank-lines-after-procedures +--break-before-boolean-operator +--no-blank-lines-after-commas +--braces-on-if-line +--braces-on-struct-decl-line +--comment-indentation25 +--declaration-comment-column25 +--no-comment-delimiters-on-blank-lines +--cuddle-else +--continuation-indentation4 +--case-indentation0 +--else-endif-column33 +--space-after-cast +--line-comments-indentation0 +--declaration-indentation1 +--dont-format-first-column-comments +--dont-format-comments +--honour-newlines +--indent-level4 +/* changed from 0 to 4 */ +--parameter-indentation4 +--line-length78 /* changed from 75 */ +--continue-at-parentheses +--no-space-after-function-call-names +--dont-break-procedure-type +--dont-star-comments +--leave-optional-blank-lines +--dont-space-special-semicolon +--tab-size4 +/* additions by Mark */ +--case-brace-indentation0 +--leave-preprocessor-space diff --git a/docs/style-guide.txt b/docs/style-guide.txt new file mode 100644 index 000000000..28fb1fbfc --- /dev/null +++ b/docs/style-guide.txt @@ -0,0 +1,224 @@ +Busybox Style Guide +=================== + +This document describes the coding style conventions used in Busybox. If you +add a new file to Busybox or are editing an existing file, please format your +code according to this style. If you are the maintainer of a file that does +not follow these guidelines, please -- at your own convenience -- modify the +file(s) you maintain to bring them into conformance with this style guide. +Please note that this is a low priority task. + +To help you format the whitespace of your programs, an ".indent.pro" file is +included in the main Busybox source directory that contains option flags to +format code as per this style guide. This way you can run GNU indent on your +files by typing 'indent myfile.c myfile.h' and it will magically apply all the +right formatting rules to your file. Please _do_not_ run this on all the files +in the directory, just your own. + +Declaration Order +----------------- + +Here is the order in which code should be laid out in a file: + + - commented author name and email address(es) + - commented GPL boilerplate + - commented description of program + - #includes and #defines + - const and globals variables + - function declarations (if necessary) + - function implementations + +Whitespace +---------- + +Tabs vs Spaces in Line Indentation: The preference in Busybox is to indent +lines with tabs. Do not indent lines with spaces and do not indents lines +using a mixture of tabs and spaces. (The 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 */ + +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 +lines is that you can set your editor to display tabs at *watever* number of +spaces is desired and the code will still look fine. + + +Operator Spacing: Put spaces between terms and operators. Example: + + Don't do this: + + for(i=0;i<num_items;i++){ + + Do this instead: + + for (i = 0; i < num_items; i++) { + + While it extends the line a bit longer, the spaced version is more + readable. An allowable exception to this rule is the situation where + excluding the spacing makes it more obvious that we are dealing with a + single term (even if it is a compund term) such as: + + if (str[idx] == '/' && str[idx-1] != '\\') + + or + + if ((argc-1) - (optind+1) > 0) + + +Bracket Spacing: If an opening bracket starts a function, it should be on the +next line with no spacing before it. However, if a bracet follows an opening +control block, it should be on the same line with a single space (not a tab) +between it and the opening control block statment. Examples: + + Don't do this: + + while (!done){ + do{ + + Do this instead: + + while (!done) { + do { + +Also, please "cuddle" your else statments by putting the else keyword on the +same line after the right bracket that closes an 'if' statment. + + Don't do this: + + if (foo) { + stmt; + } + else { + stmt; + } + + Do this instead: + + if (foo) { + stmt; + } else { + stmt; + } + + +Paren Spacing: Put a space between C keywords and left parens, but not between +function names and the left paren that starts it's parameter list (whether it +is being declared or called). Examples: + + Don't do this: + + while(foo) { + for(i = 0; i < n; i++) { + + Do this instead: + + while (foo) { + for (i = 0; i < n; i++) { + + Do functions like this: + + static int my_func(int foo, char bar) + ... + baz = my_func(1, 2); + +Variable and Function Names +--------------------------- + +Use the K&R style with names in all lower-case and underscores occasionally +used to seperate words (e.g. "variable_name" and "numchars" are both +acceptable). Using underscores makes variable and function names more readable +because it looks like whitespace; using lower-case is easy on the eyes. + +Note: The Busybox codebase is very much a mixture of code gathered from a +variety of locations. This explains why the current codebase contains such a +plethora of different naming styles (Java, Pascal, K&R, just-plain-weird, +etc.). The K&R guideline explained above should therefore be used on new files +that are added to the repository. Furthermore, the maintainer of an existing +file that uses alternate naming conventions should -- at his own convenience +-- convert those names over to K&R style; converting variable names is a very +low priority task. Perhaps in the future we will include some magical Perl +script that can go through and convert files--left as an exersize to the +reader. + + +Tip and Pointers +---------------- + +The following are simple coding guidelines that should be followed: + + - Don't use a '#define var 80' when you can use 'static const int var 80' + instead. This makes the compiler do typechecking for you (rather than + relying on the more error-prone preprocessor) and it makes debugging + programs much easier since the value of the variable can be easily queried. + + - If a const variable is used in only one function, do not make it global to + the file. Instead, declare it inside the function body. + + - Inside applet files, all functions should be declared static so as to keep + the global namespace clean. The only exception to this rule is the + "applet_main" function which must be declared extern. + + - If you write a function that performs a task that could be useful outside + the immediate file, turn it into a general-purpose function with no ties to + any applet and put it in the utility.c file instead. + + - Put all help/usage messages in usage.c. Put other strings in messages.c + (Side Note: we might want to use a single file instead of two, food for + thought). + + - Do not use old-style function declarations that declare variable types + between the parameter list and opening bracket. Example: + + Don't do this: + + int foo(parm1, parm2) + char parm1; + float parm2; + { + .... + + Do this instead: + + int foo(char parm1, float parm2) + { + .... + + - Please use brackets on all if and else statements, even if it is only one + line. Example: + + Don't do this: + + if (foo) + stmt; + else + stmt; + + Do this instead: + + if (foo) { + stmt; + } else { + stmt; + } + + The "bracketless" approach is error prone because someday you might add a + line like this: + + if (foo) + stmt; + new_line(); + else + stmt; + + And the resulting behavior of your program would totally bewilder you. + (Don't laugh, it happens to us all.) Remember folks, this is C, not + Python. |