Numerous spelling / grammar corrections from Larry Doolittle
<ldoolitt@recycle.lbl.gov>, as well as a few additions / clarifications.
diff --git a/docs/style-guide.txt b/docs/style-guide.txt
index 72d3b93..36974d7 100644
--- a/docs/style-guide.txt
+++ b/docs/style-guide.txt
@@ -21,11 +21,12 @@
Here is the order in which code should be laid out in a file:
+ - commented program name and one-line description
- commented author name and email address(es)
- commented GPL boilerplate
- - commented description of program
+ - commented longer description / notes for the program (if needed)
- #includes and #defines
- - const and globals variables
+ - const and global variables
- function declarations (if necessary)
- function implementations
@@ -37,7 +38,7 @@
up front.
-Tabs vs Spaces in Line Indentation
+Tabs vs. Spaces in Line Indentation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The preference in Busybox is to indent lines with tabs. Do not indent lines
@@ -56,7 +57,7 @@
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
+lines is that you can set your editor to display tabs at *whatever* number of
spaces is desired and the code will still look fine.
@@ -76,7 +77,7 @@
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:
+ single term (even if it is a compound term) such as:
if (str[idx] == '/' && str[idx-1] != '\\')
@@ -89,12 +90,20 @@
~~~~~~~~~~~~~~~
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
+next line with no spacing before it. However, if a bracket 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:
+between it and the opening control block statement. Examples:
Don't do this:
+ while (!done)
+ {
+
+ do
+ {
+
+ Don't do this either:
+
while (!done){
do{
@@ -121,7 +130,7 @@
while (foo) {
for (i = 0; i < n; i++) {
- Do functions like this:
+ But do functions like this:
static int my_func(int foo, char bar)
...
@@ -131,8 +140,8 @@
Cuddled Elses
~~~~~~~~~~~~~
-Also, please "cuddle" your else statments by putting the else keyword on the
-same line after the right bracket that closes an 'if' statment.
+Also, please "cuddle" your else statements by putting the else keyword on the
+same line after the right bracket that closes an 'if' statement.
Don't do this:
@@ -151,25 +160,36 @@
stmt;
}
+The exception to this rule is if you want to include a comment before the else
+block. Example:
+
+ if (foo) {
+ stmts...
+ }
+ /* otherwise, we're just kidding ourselves, so re-frob the input */
+ else {
+ other_stmts...
+ }
+
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
+used to separate 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,
+variety of sources. This explains why the current codebase contains such a
+hodge-podge 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.
+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 exercise to the reader for
+now.
Tip and Pointers
@@ -177,31 +197,34 @@
The following are simple coding guidelines that should be followed:
- - When in doubt about the propper behavior of a busybox program (output,
+ - When in doubt about the proper behavior of a Busybox program (output,
formatting, options, etc.), model it after the equivalent GNU program.
Doesn't matter how that program behaves on some other flavor of *NIX;
doesn't matter what the POSIX standard says or doesn't say, just model
- busybox programs after their GNU counterparts and nobody has to get hurt.
+ Busybox programs after their GNU counterparts and nobody has to get hurt.
- 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
+ instead. This makes the compiler do type checking 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.
+ programs much easier since the value of the variable can be easily
+ displayed.
- 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
+ the global name space 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).
+ - Put all help/usage messages in usage.c. Put other strings in messages.c.
+ Putting these strings into their own file is a calculated decision designed
+ to confine spelling errors to a single place and aid internationalization
+ efforts, if needed. (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:
@@ -218,7 +241,9 @@
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.
+ the "not" (!) operator makes it look like you are testing for an error. In
+ a more perfect world, we would have a streq() function in the string
+ library, but that ain't the world we're living in.
- Do not use old-style function declarations that declare variable types
between the parameter list and opening bracket. Example: