242 lines
7.0 KiB
Plaintext
242 lines
7.0 KiB
Plaintext
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).
|
|
|
|
- There's a right way and a wrong way to test for sting equivalence with
|
|
strcmp:
|
|
|
|
The wrong way:
|
|
|
|
if (!strcmp(string, "foo")) {
|
|
...
|
|
|
|
The right way:
|
|
|
|
if (strcmp(string, "foo") == 0){
|
|
...
|
|
|
|
The use of the "equals" (==) operator in the latter example makes it much
|
|
more obvious that you are testing for equivalence. The former example with
|
|
the "not" (!) operator makes it look like you are testing for an error.
|
|
|
|
- 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.
|