X-Git-Url: https://git.librecmc.org/?a=blobdiff_plain;f=docs%2Fstyle-guide.txt;h=ba0cdbaa487e7f6579746c7d6101e9a3d8416bc4;hb=6ced427a6debb71967a8b9cebc12e31c08de0f6a;hp=c71f1e6098d15df8c5115fb2b4622f78c3e6b5fb;hpb=7ddaf7caaeb2b13d3ddf66ab6715a2eaa6cc9ed3;p=oweals%2Fbusybox.git diff --git a/docs/style-guide.txt b/docs/style-guide.txt index c71f1e609..ba0cdbaa4 100644 --- a/docs/style-guide.txt +++ b/docs/style-guide.txt @@ -51,13 +51,13 @@ indentation style in the Apache and Postfix 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 */ + \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, 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 @@ -126,6 +126,15 @@ between it and the opening control block statement. Examples: do { +Exceptions: + + - if you have long logic statements that need to be wrapped, then uncuddling + the bracket to improve readability is allowed: + + if (some_really_long_checks && some_other_really_long_checks \ + && some_more_really_long_checks) + { + do_foo_now; Spacing around Parentheses ~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -252,7 +261,7 @@ files, you can do the following in the busybox directory: If you want to convert all the non-K&R vars in your file all at once, follow these steps: - - In the busybox directory type 'scripts/mk2knr.pl files-to-convert'. This + - In the busybox directory type 'examples/mk2knr.pl files-to-convert'. This does not do the actual conversion, rather, it generates a script called 'convertme.pl' that shows what will be converted, giving you a chance to review the changes beforehand. @@ -266,10 +275,10 @@ these steps: conversion. - Compile and see if everything still works. - + Please be aware of changes that have cascading effects into other files. For example, if you're changing the name of something in, say utility.c, you -should probably run 'scripts/mk2knr.pl utility.c' at first, but when you run +should probably run 'examples/mk2knr.pl utility.c' at first, but when you run the 'convertme.pl' script you should run it on _all_ files like so: './convertme.pl *.[ch]'. @@ -293,13 +302,13 @@ Use 'const var' for declaring constants. #define var 80 Do this instead, when the variable is in a header file and will be used in - several source files: + several source files: - const int var = 80; + const int var = 80; Or do this when the variable is used only in a single source file: - static const int var = 80; + static const int var = 80; Declaring variables as '[static] const' gives variables an actual type and makes the compiler do type checking for you; the preprocessor does _no_ type @@ -336,14 +345,14 @@ The Folly of #ifdef Code cluttered with ifdefs is difficult to read and maintain. Don't do it. Instead, put your ifdefs at the top of your .c file (or in a header), and conditionally define 'static inline' functions, (or *maybe* macros), which are -used in the code. +used in the code. Don't do this: ret = my_func(bar, baz); if (!ret) return -1; - #ifdef BB_FEATURE_FUNKY + #ifdef CONFIG_FEATURE_FUNKY maybe_do_funky_stuff(bar, baz); #endif @@ -351,7 +360,7 @@ used in the code. (in .h header file) - #ifdef BB_FEATURE_FUNKY + #ifdef CONFIG_FEATURE_FUNKY static inline void maybe_do_funky_stuff (int bar, int baz) { /* lotsa code in here */ @@ -445,7 +454,7 @@ First, some background to put this discussion in context: Static buffers look like this in code: /* in a .c file outside any functions */ - static char *buffer[BUFSIZ]; /* happily used by any function in this file, + static char buffer[BUFSIZ]; /* happily used by any function in this file, but ick! big! */ The problem with these is that any time any busybox app is run, you pay a @@ -487,7 +496,7 @@ very limited stack space (e.g., uCLinux). A macro is declared in busybox.h that implements compile-time selection between xmalloc() and stack creation, so you can code the line in question as - RESERVE_BB_BUFFER(buffer, BUFSIZ); + RESERVE_CONFIG_BUFFER(buffer, BUFSIZ); and the right thing will happen, based on your configuration. @@ -610,7 +619,7 @@ 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 +There is an optimal amount 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, the following example @@ -650,7 +659,7 @@ line in the midst of your #includes: And a code block similar to the following near the top of your applet_main() routine: - while ((opt = getopt(argc, argv, "abc")) > 0) { + while ((opt = getopt(argc, argv, "abc")) > 0) { switch (opt) { case 'a': do_a_opt = 1;