[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