lkml.org 
[lkml]   [2007]   [May]   [26]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
    Patch in this message
    /
    Date
    From
    Subject[PATCH] [condingstyle] Add chapter on tests

    Based in part on Auke's patch.

    Signed-off-by: Jan Engelhardt <jengelh@gmx.de>

    ---
    Documentation/CodingStyle | 74 +++++++++++++++++++++++++++++++++++++++-------
    1 file changed, 64 insertions(+), 10 deletions(-)

    Index: linux-2.6.22-rc3/Documentation/CodingStyle
    ===================================================================
    --- linux-2.6.22-rc3.orig/Documentation/CodingStyle
    +++ linux-2.6.22-rc3/Documentation/CodingStyle
    @@ -407,7 +407,61 @@ out:
    return result;
    }

    - Chapter 8: Commenting
    + Chapyer 8: Tests
    +
    +Testing return values from function calls can get complex when you need
    +to re-use the value later on. You should store the value before doing
    +any tests on it. Do not assign values inside a condition to another
    +variable.
    +
    + err = test_something();
    + if (err) {
    + printk(KERN_ERR "Error: test_something() failed\n");
    + return err;
    + }
    +
    +Testing for a flag, as done in the following example, is redundant and
    +can be shortened.
    +
    + if ((v & GFP_KERNEL) == GFP_KERNEL)
    + return;
    +
    +should become
    +
    + if (v & GFP_KERNEL)
    + return;
    +
    +The same goes for functions that return a bool:
    +
    + if (is_prime(number) == true)
    + return 0;
    + if (is_prime(number) == false)
    + return 1;
    +
    +should be:
    +
    + if (is_prime(number))
    + return 0;
    + if (!is_prime(number))
    + return 1;
    +
    +As far as pointers or functions returning an integer are concerned,
    +using long form tests helps to distinguish between pointers and bools
    +or functions returning boolean or integer, respectively.
    +Examples are:
    +
    + if (p == NULL)
    + return 1;
    + if (!p)
    + return 0;
    +
    + if (strcmp(haystack, needle) == 0)
    + return 1;
    + if (!strcmp(haystack, needle))
    + return 0;
    +
    +
    + Chapter 9: Commenting

    Comments are good, but there is also a danger of over-commenting. NEVER
    try to explain HOW your code works in a comment: it's much better to
    @@ -447,7 +501,7 @@ multiple data declarations). This leave
    item, explaining its use.


    - Chapter 9: You've made a mess of it
    + Chapter 10: You've made a mess of it

    That's OK, we all do. You've probably been told by your long-time Unix
    user helper that "GNU emacs" automatically formats the C sources for
    @@ -495,7 +549,7 @@ re-formatting you may want to take a loo
    remember: "indent" is not a fix for bad programming.


    - Chapter 10: Kconfig configuration files
    + Chapter 11: Kconfig configuration files

    For all of the Kconfig* configuration files throughout the source tree,
    the indentation is somewhat different. Lines under a "config" definition
    @@ -531,7 +585,7 @@ For full documentation on the configurat
    Documentation/kbuild/kconfig-language.txt.


    - Chapter 11: Data structures
    + Chapter 12: Data structures

    Data structures that have visibility outside the single-threaded
    environment they are created and destroyed in should always have
    @@ -562,7 +616,7 @@ Remember: if another thread can find you
    have a reference count on it, you almost certainly have a bug.


    - Chapter 12: Macros, Enums and RTL
    + Chapter 13: Macros, Enums and RTL

    Names of macros defining constants and labels in enums are capitalized.

    @@ -617,7 +671,7 @@ The cpp manual deals with macros exhaust
    covers RTL which is used frequently with assembly language in the kernel.


    - Chapter 13: Printing kernel messages
    + Chapter 14: Printing kernel messages

    Kernel developers like to be seen as literate. Do mind the spelling
    of kernel messages to make a good impression. Do not use crippled
    @@ -628,7 +682,7 @@ Kernel messages do not have to be termin
    Printing numbers in parentheses (%d) adds no value and should be avoided.


    - Chapter 14: Allocating memory
    + Chapter 15: Allocating memory

    The kernel provides the following general purpose memory allocators:
    kmalloc(), kzalloc(), kcalloc(), and vmalloc(). Please refer to the API
    @@ -647,7 +701,7 @@ from void pointer to any other pointer t
    language.


    - Chapter 15: The inline disease
    + Chapter 16: The inline disease

    There appears to be a common misperception that gcc has a magic "make me
    faster" speedup option called "inline". While the use of inlines can be
    @@ -674,7 +728,7 @@ appears outweighs the potential value of
    something it would have done anyway.


    - Chapter 16: Function return values and names
    + Chapter 17: Function return values and names

    Functions can return values of many different kinds, and one of the
    most common is a value indicating whether the function succeeded or
    @@ -708,7 +762,7 @@ result. Typical examples would be funct
    NULL or the ERR_PTR mechanism to report failure.


    - Chapter 17: Don't re-invent the kernel macros
    + Chapter 18: Don't re-invent the kernel macros

    The header file include/linux/kernel.h contains a number of macros that
    you should use, rather than explicitly coding some variant of them yourself.
    -
    To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
    the body of a message to majordomo@vger.kernel.org
    More majordomo info at http://vger.kernel.org/majordomo-info.html
    Please read the FAQ at http://www.tux.org/lkml/
    \
     
     \ /
      Last update: 2007-05-26 22:17    [W:0.026 / U:90.080 seconds]
    ©2003-2016 Jasper Spaans. hosted at Digital OceanAdvertise on this site