aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--docs/style-guide.txt89
1 files changed, 75 insertions, 14 deletions
diff --git a/docs/style-guide.txt b/docs/style-guide.txt
index 4d0c7ca17..374a822b2 100644
--- a/docs/style-guide.txt
+++ b/docs/style-guide.txt
@@ -109,6 +109,13 @@ between it and the opening control block statement. Examples:
while (!done){
do{
+ And for heaven's sake, don't do this:
+
+ while (!done)
+ {
+ do
+ {
+
Do this instead:
while (!done) {
@@ -175,6 +182,7 @@ block. Example:
+
Variable and Function Names
---------------------------
@@ -183,16 +191,32 @@ 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.
+ Frowned upon:
+
+ hitList
+ TotalChars
+ szFileName (blech)
+
+ Preferred:
+
+ hit_list
+ total_chars
+ file_name
+
+The exception to this rule are enums, macros, and constant variables which
+should all be in upper-case, with words optionally seperatedy by underscores
+(i.e. FIFOTYPE, ISBLKDEV()).
+
Note: The Busybox codebase is very much a mixture of code gathered from a
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 exercise to the reader for
-now.
+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 variable names, left as an exercise for
+the reader for now.
@@ -388,26 +412,26 @@ line. Example:
Don't do this:
if (foo)
- stmt;
- else
- stmt;
+ stmt1;
+ stmt2
+ stmt3;
Do this instead:
if (foo) {
- stmt;
- } else {
- stmt;
+ stmt1;
}
+ stmt2
+ stmt3;
The "bracketless" approach is error prone because someday you might add a line
like this:
if (foo)
- stmt;
+ stmt1;
new_line();
- else
- stmt;
+ stmt2
+ stmt3;
And the resulting behavior of your program would totally bewilder you. (Don't
laugh, it happens to us all.) Remember folks, this is C, not Python.
@@ -438,3 +462,40 @@ support ancient, antediluvian compilers. To our good fortune, we have access
to more modern compilers and the old declaration syntax is neither necessary
nor desired.
+
+Emphasizing Logical Blocks
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Organization and readability are improved by putting extra newlines around
+blocks of code that perform a single task. These are typically blocks that
+begin with a C keyword, but not always.
+
+Furthermore, you should put a single comment (not necessarily one line, just
+one comment) before the block, rather than commenting each and every line.
+There is an optimal ammount of commenting that a program can have; you can
+comment too much as well as too little.
+
+A picture is really worth a thousand words here, so here is an example that
+illustrates emphasizing logical blocks:
+
+ while (line = get_line_from_file(fp)) {
+
+ /* eat the newline, if any */
+ if (line[strlen(line)-1] == '\n') {
+ line[strlen(line)-1] = '\0';
+ }
+
+ /* ignore blank lines */
+ if (strlen(file_to_act_on) == 0) {
+ continue;
+ }
+
+ /* if the search string is in this line, print it,
+ * unless we were told to be quiet */
+ if (strstr(line, search) && !be_quiet) {
+ puts(line);
+ }
+
+ /* clean up */
+ free(line);
+ }