lkml.org 
[lkml]   [2004]   [Feb]   [13]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
    Patch in this message
    /
    From
    SubjectPATCH, RFC: Version 3 of 2.6 Codingstyle
    Date
    Changes:

    Add reference to scripts/Lindent

    Cleanups, spelling fixes and numbering of chapters.

    Regards
    Michael

    Patch against Version 2. Patch against in-kernel version attached

    --- CodingStyle.mhf.orig.2 2004-02-13 16:42:07.000000000 +0800
    +++ CodingStyle 2004-02-14 09:29:55.000000000 +0800
    @@ -42,7 +42,7 @@
    do_something_everytime;

    Outside of comments and except in Kconfig, spaces are never used for
    -indentation.
    +indentation, and the above example is deliberately broken.

    Don't leave whitespace at the end of lines.

    @@ -52,10 +52,12 @@
    Coding style is all about readability and maintainability using commonly
    available tools.

    +The limit on the length of lines is 80 columns and this is a hard limit.
    +
    Statements longer than 80 columns will be broken into sensible chunks.
    -Descendant's are always shorter than the parent and are placed substantially
    -to the right. The same applies to function headers with a long argument list.
    -Long strings are as well broken into smaller strings.
    +Descendants are always substantially shorter than the parent and are placed
    +substantially to the right. The same applies to function headers with a long
    +argument list. Long strings are as well broken into smaller strings.

    void fun(int a, int b, int c)
    {
    @@ -67,8 +69,7 @@
    next_statement;
    }

    -
    - Chapter : Placing Braces
    + Chapter 3: Placing Braces

    The other issue that always comes up in C styling is the placement of
    braces. Unlike the indent size, there are few technical reasons to
    @@ -121,7 +122,7 @@
    comments on.


    - Chapter : Naming
    + Chapter 4: Naming

    C is a Spartan language, and so should your naming be. Unlike Modula-2
    and Pascal programmers, C programmers do not use cute names like
    @@ -154,10 +155,10 @@
    See next chapter.


    - Chapter : Functions
    + Chapter 5: Functions

    Functions should be short and sweet, and do just one thing. They should
    -fit on one or two screens full of text (the ISO/ANSI screen size is 80x24,
    +fit on one or two screenfuls of text (the ISO/ANSI screen size is 80x24,
    as we all know), and do one thing and do that well.

    The maximum length of a function is inversely proportional to the
    @@ -181,10 +182,10 @@
    and it gets confused. You know you're brilliant, but maybe you'd like
    to understand what you did 2 weeks from now.

    -Centralized exiting of functions
    + Chapter 6: Centralized exiting of functions

    -Albeit deprecated by some people, the goto statement is used frequently
    -by compilers in form of the unconditional jump instruction.
    +Albeit deprecated by some people, the equivalent of the goto statement is
    +used frequently by compilers in form of the unconditional jump instruction.

    The goto statement comes in handy when a function exits from multiple
    locations and some common work such as cleanup has to be done.
    @@ -193,16 +194,17 @@

    - unconditional statements are easier to understand and follow
    - nesting is reduced
    -- errors by not updating individual exit points when making modifications
    - are prevented
    +- errors by not updating individual exit points when making
    + modifications are prevented
    - saves the compiler work to optimize redundant code away ;)

    int fun(int )
    {
    int result = 0;
    char *buffer = kmalloc(SIZE);
    + lock(something);

    - if (buffer == 0) {
    + if (buffer == NULL) {
    result = -1;
    goto out;
    }
    @@ -216,12 +218,13 @@
    }
    ...
    out:
    - if (buffer)
    - kfree(buffer);
    + unlock(something);
    + if (buffer != NULL) // This test is not needed for kfree
    + kfree(buffer); // as kfree checks pointer
    return result;
    }

    - Chapter : Commenting
    + Chapter 7: 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
    @@ -238,7 +241,7 @@
    it.


    - Chapter : You've made a mess of it
    + Chapter 8: 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
    @@ -263,7 +266,7 @@
    to add

    (setq auto-mode-alist (cons '("/usr/src/linux.*/.*\\.[ch]$" . linux-c-mode)
    - auto-mode-alist))
    +auto-mode-alist))

    to your .emacs file if you want to have linux-c-mode switched on
    automagically when you edit source files under /usr/src/linux.
    @@ -276,14 +279,15 @@
    However, that's not too bad, because even the makers of GNU indent
    recognize the authority of K&R (the GNU people aren't evil, they are
    just severely misguided in this matter), so you just give indent the
    -options "-kr -i8" (stands for "K&R, 8 character indents").
    +options "-kr -i8" (stands for "K&R, 8 character indents"), or use
    +"scripts/Lindent", which indents in the latest style.

    "indent" has a lot of options, and especially when it comes to comment
    -re-formatting you may want to take a look at the manual page. But
    +re-formatting you may want to take a look at the man page. But
    remember: "indent" is not a fix for bad programming.


    - Chapter : Configuration-files
    + Chapter 9: Configuration-files

    For configuration options (arch/xxx/Kconfig, and all the Kconfig files),
    somewhat different indentation is used.
    @@ -308,7 +312,7 @@
    experimental options should be denoted (EXPERIMENTAL).


    - Chapter : Data structures
    + Chapter 10: Data structures

    Data structures that have visibility outside the single-threaded
    environment they are created and destroyed in should always have
    @@ -339,9 +343,9 @@
    have a reference count on it, you almost certainly have a bug.


    - Chapter : Inlines, Enums and Macros
    + Chapter 11: Macros, Enums and Inline functions

    -Macros defining constants and values in enums are capitalized.
    +Names of macros defining constants and labels in enums are capitalized.

    #define CONSTANT 0x12345

    @@ -358,10 +362,9 @@
    do { \
    if (a == 5) \
    do_this(b,c); \
    - \
    } while (0)

    -Things to avoid when doing macros:
    +Things to avoid when using macros:

    1) macros that affect control flow:

    @@ -374,7 +377,7 @@
    is a _very_ bad idea. It looks like a function call but exits the "calling"
    function; don't break the internal parsers of those who will read the code.

    -2) macros that depend on having a local variable with magic name:
    +2) macros that depend on having a local variable with a magic name:

    #define FOO(val) bar(index, val)

    @@ -382,16 +385,16 @@
    code and it's prone to breakage from seemingly innocent changes.

    3) macros with arguments that are used as l-values: FOO(x) = y; will
    -bite you if somebody e.g. turns FOO into inlined function.
    +bite you if somebody e.g. turns FOO into an inline function.

    -4) forgetting about sideeffects. Macros defining expressions must enclose the
    -expression in parenthesis. Note that this does not eliminate all side effects.
    +4) forgetting about side effects: macros defining expressions must enclose each
    +parameter and the expression in parentheses.

    #define CONSTEXP (CONSTANT | 3)
    #define MACWEXP(a,b) ((a) + (b))


    - Chapter : Printing kernel messages
    + Chapter 12: 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
    @@ -400,5 +403,3 @@
    Kernel messages do not have to be terminated with a period.

    Printing numbers in parenthesis (%d) adds no value and should be avoided.
    -
    -
    \
     
     \ /
      Last update: 2005-03-22 14:00    [W:0.033 / U:0.988 seconds]
    ©2003-2016 Jasper Spaans. hosted at Digital OceanAdvertise on this site