[BusyBox] bug#1016: RFC: Busybox Style Guide Document

[Mark Whitley]

On Wed, Jul 19, 2000 at 05:08:19PM -0700, Jon McClintock wrote:
> > I propose that a coding style guide be written for Busybox.
>
> I think this is a great idea.

Thanks for the support, Jon. :-)

> >  - Variable / Function Naming - currently there are two styles widely in
> 
> I prefer to use K&R when I'm doing C (non OO) work.

So far that's two votes for K&R (me & Jon). Anyone want to offer an
alternative / contrary point of view?

> >  - Bracket Placement - There is already fairly unanimous use of the K&R
> 
> "cuddled" looks cleaner to me.

I agree; non-cuddled feels a bit "airy".

> >  - 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.
> 
> I have no objections to the order given.

Any objections from anyone else?

> > 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.
> 
> I think a formalized style guide is good. As someone who's programmed using
> half a dozen different styles, it helps to have something to orient yourself
> by...

And this was the reason why I thought it would be a good idea to propose such
a document. Having a consistent style through all the source code means that
there's one less thing that you have to try to decipher.


A few other points I thought of that should have some consensus on:

 - Tabs vs Spaces: I prefer to indent lines with tabs rather than spaces; I do
   not like code that indents lines with spaces and I do not like code that
   indents lines using a mixture of code and spaces. (The indentation style in
   the Apache 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, I prefer 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
   and it will still look fine.


 - Operator Spacing: I tend to prefer putting spaces between terms and
   operators. Example:

   I don't care for this style:

		for(i=0;i<num_items;i++){

	I much prefer this style:

		for (i = 0; i < num_items; i++) {

	While it extends the line a bit longer, I find the spaced version more
	readable. The exception(s) to this rule are situations 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)

	Again, anyone agree / disagree?


 - Paren / 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:

	I don't care for this style:

		while (!done){
		do{

	I prefer this style:

		while (!done) {
		do {

	WRT Paren spacing, I prefer to have a space between C keywords and left
	parens, but I dont' think it's necessary to put a space between function
	names and parens. Examples:

	I don't like this:

		while(foo) {
		for(i = 0; i < n; i++) {

	I prefer this:

		while (foo) {
		for (i = 0; i < n; i++) {

	This sort of thing is OK by me:

		static int my_func(int foo, char bar)
		...
		baz = my_func(1, 2);

	Anyone have a different view on this?


		
I will begin working on a .indent.pro file that can be put into the busybox/
source directory so that people can just type "indent *.[ch]" within that
directory and indent all the source files. Additionally, I'll probably make a
Makefile target that does exactly that. Before I check the .indent.pro file in
to CVS, I will be sure to wait until I've received a little more consensus
regarding these style issues.

Thanks, y'all.

Mark Whitley
markw at lineo.com