[BusyBox] bug#1016: RFC: Busybox Style Guide Document
Mark Whitley
markw at lineo.com
Wed Jul 19 17:53:45 UTC 2000
Package: busybox
Version: 0.46
I propose that a coding style guide be written for Busybox. I will volunteer
to write this document, but I want to get consensus on a couple of things. The
following is a brief outline of topics I think the style guide should cover:
- Variable / Function Naming - currently there are two styles widely in use
1) the K&R style with all lower-case and underscores occasionally used to
seperate words (variable_name, numchars), and 2) the Java style name with
the first word lower-cased and following words appended with the first
letter capitalized (variableName, longerVariableName). My personal
preference is to use the K&R style (I find it more readable) but it is more
important to go with the style that is preferred by the majority of busybox
hackers and be consistent with it.
- Bracket Placement - There is already fairly unanimous use of the K&R style
of putting the opening bracket on the same line as the opening control
block statement (if, while, switch, etc.), excepting for opening brackets
taht open a function which are put on the line just below. The only thing I
think we need to build consensus on is use of "cuddled" else statements ( }
else { ) vs non-cuddled ( }\nelse { ).
- Declaration Order - The order in which code should be laid out in a file.
There are already some fairly uniform conventions used here: commented
description first, then #includes and #defines, then const and globals
vars, then function declarations, then actual functions. I think we should
write down that this is how we do it.
- Tip and Pointers - The style guide should include a section that gives
brief advice on good coding skills. Things like:
- Don't use a '#define var 80' when you can use 'static const int var
80' instead.
- 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 (note: we might want to use a single file instead of two,
food for thought).
Ideally, this file could be text/sgml and reside in the docs/ directory with
other documentation. I believe a style guide document will become more
important as more new contributors begin hacking at busybox so they can have
some set guidelines to follow. It will help us all to be able to read each
other's code.
Also, once the style is decided upon and the document is written, part of the
document should include a list of flags that can be passed to GNU indent to
indent the code as per our style. If it is deemed appropriate, we might even
put a pre-checkin filter into CVS that runs all checked-in code through that
indentation filter.
Alternatively, this bug could be closed with a resolution of "This doesn't
need fixing; the style is fine as it is and everyone follows pretty good
conventions anyway." If this is indeed what the consensus turns out to be,
then so be it.
Please reply to this on the mailing list with answers to various questions
posed and any additional comments.
Mark Whitley
markw at lineo.com
More information about the busybox
mailing list