[prev in list] [next in list] [prev in thread] [next in thread] 

List:       busybox
Subject:    bug#1016: [BusyBox] bug#1016: RFC: Busybox Style Guide Document
From:       Erik Andersen <andersen () lineo ! com>
Date:       2000-07-20 23:09:35
[Download RAW message or body]

On Wed Jul 19, 2000 at 11:53:45AM -0600, Mark Whitley wrote:
> 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.

One great advantage of busybox is that it has been able to freely include bits
and pieces of code from all over.  This is also resulted in the current
variable naming mess.  I usually use whatever variable style is already in use
in a file.  If someone want to go through and rename all the variables to  K&R
style, I'd be ok with that -- but it will be a huge thankless job with very
little to show for it (except a potential ocean of search-and-replace bugs).

>  - 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 { ).

I used the following to initially indent everything, as this fits my personal style
pretty well.

    alias indent='indent -bad -bap -bbo -nbc -br -brs -c33 -cd33 -ncdb -ce -ci4 \
	-cli0 -cp33 -cs -d0 -di1 -nfc1 -nfca -hnl -i4 -ip0 -l75 -lp -npcs -npsl \
	-nsc -nsob -nss -ts4 '


>  - 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.

Sure.

>  - 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.

Hey, if you have the time and interest -- go for it,

 -Erik

--
Erik B. Andersen   email:  andersen@lineo.com
--This message was written using 73% post-consumer electrons--




[prev in list] [next in list] [prev in thread] [next in thread]