Coding Style in Linux kernelPeter Chang2012/06/17

Reference

“Linux Kernel Coding Style”, Linus Torvals, https://computing.llnl.gov/linux/slurm/coding_style.pdf

“Documentation / Coding-Style”, Greg Kroah-Hartman, IBM, Linux Symposium 2002

(Slide version: http://www.kroah.com/linux/talks/ols_2002_kernel_codingstyle_talk/html/index.html)

http://www.kernel.org/doc/Documentation/CodingStyle

“First off, I'd suggest printing out a copy of the GNU coding standards, and NOT read it.

Burn them, it's a great symbolic gesture.”~ Linus Torvalds

Indentation

Indentation

All tabs are 8 characters.

Use tabs.

If your code need 3 layers of indentation, it’s your problem. Solve it!

Indentation

Don’t put two statement in the same line.

Use a good editor. Don’t put andy empty line in the end of any file.

Indentation

Put switch and case into the same layer of indentation

Indentation

Indentation

Good examples:

fs/*

kernel/*

Bad examples:

drivers/scsi/sg.c

Break long lines & strings

Break long lines & strings

There are only 80 char. in a line.Because we hate this:

Break long lines & strings

Braces

Braces

Braces

Braces

Braces

Braces

Braces

Braces

Braces

Good examples:

drivers/scsi/qla1280.c

kernel/*.c

Bad examples:

fs/devfs/*

Spaces

Spaces

“To be, or not to be”

Spaces

Use a space after these keywords:

if, switch, case, for, do, while

Do not add spaces after these keywords:

sizeof, typeof, alignof, __attribute__

Spaces

Good example:

s = sizeof(struct file);

Suck example:

s=sizeof( struct file );

Spaces

Add a space before and after the following binary and ternary operators:

= , + , - , * , /

< , > , % , & , | , ^

<= , >= , == , != , ? , :

Spaces

DO NOT Add a space after the following operators:

&, *, +, -, ~, !, sizeof, typeof, alignof, __attribute__, define

Spaces

DO NOT add a space before and after the following operators:

++,--

Spaces

DO NOT add a space before and after the following operators:

.

->

Naming

Naming

Be descriptive

Be concise

Good example:

void enable_mem_mailbox();

Naming

No MiXedCaSe

Bad examples:

int CommandAllocationGroupSize;

void DAC960_V1_EnableMemoryMailboxInterface();

Naming

Global variable should be use only if they are absolutely necessary.

Naming

Local variable should be short and the point

Good example:

i,j ( as a counter for a loop )

Bad example:

loop_counter

Naming

Don’t encoding the type of a function into the name (a.k.a. Hungarian notation).

“It’s brain damaged” ~ Linus Torvalds

Functions

Functions

Do one thing, and do it well

Short, one or two screens of text

Functions

Okay to have longer function doing small different things

Functions

“如果你寫出了⼀一個很複雜的function，表示你可能程度比高中⼀一年級的學生還差，因為你不會用function”~ Linus Torvalds

Functions

If more than 10 local variables, it’s too complex

Functions

“人最多同時只能記7件不同的事情。如果你覺得你是天才，那或許你兩個星期後就還看的懂你那複雜的函式”~ Linus Torvalds

Functions

Separate different functions with a blank line

If your function will be exported, use EXPORT* macro

Functions

Indentation

Good examples:

fs/*.c

Bad examples:

drivers/hotplug/ibmphp_res.c

include WTF 370 lines

drivers/usb/serial/usbserials.c

use WTF 21 local variables

GOTOCentralize exiting of functions

被封印的GOTO

“危險，不要用”

~ 好像小時候聽大人講過

“下⼀一節是要講Goto，但我們跳過，你們寫程式也不要用Goto”

~ 好像當初上大⼀一程設上課有講過

只是歷史遺跡？

組合語言發展過來的遺跡？

jump？

branch？

難道GOTO錯了嗎?

As the matter of fact, ...

The equivalent to GOTO statement is used frequently by compiler.

For what?

Unconditional jump instruction

Timing of using GOTO

Let function from multiple exit to only one exit

Reason of using GOTO

Unconditional statements are easier to understand and follow

nested is reduced!!!

errors by not updating individual exit points when making modifications are prevented

saves the compiler work to optimize redundant code away ;)

Example of using GOTO

Comment

Comments

Bad comments

explain how code works

say who wrote this function

have last modified date

have other trivial things

Comments

Good comments

explain what

explain why

should be at the beginning of function

Comments

Do not use:

// statement of comment ( C99-style )

Do use:

/* statement of comment ( C89-style) */

Comments

Comments

Comments

Kconfig

Indentation of Kconfig

Lines under a "config" definition are indented with one tab

help text is indented an additional two spaces

Indentation of Kconfig

Unstable Features in Kconfig

Features that might still be considered unstable should be defined as dependent on "EXPERIMENTAL"

Unstable Features in Kconfig

Dangerous feature in Kconfig

seriously dangerous features should advertise this prominently in their prompt string

Dangerous feature in Kconfig

Macro, enum, RTL

CAPITALIZE

Names of macros defining constants

labels in enums

For defining several related constants

CAPITALIZE

Example:

#define CONSTANT 0xffff0000

LOOOOONG Macro

Macros with multiple statements should be enclosed in a do - while block

LOOOOONG Macro

Don’t use macro in these cases

1. macros that affect control flow

It looks like a function call but exits the "calling" function; don't break the internal parsers of those who will read the code.

Don’t use macro in these cases

Don’t use macro in these cases

2. macros that depend on having a local variable with a magic name

might look like a good thing, but it's confusing as hell when one reads the code and it's prone to breakage from seemingly innocent changes.

Don’t use macro in these cases

Example for 2:

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

Don’t use macro in these cases

3. macros with arguments that are used as l-values

Ex: FOO(x) = y;

will bite you if somebody e.g. turns FOO into an inline function

Don’t use macro in these cases

4. forgetting about precedence

macros defining constants using expressions must enclose the expression in parentheses.

Beware of similar issues with macros using parameters.

Don’t use macro in these cases

Allocate memory

Function return value and names

Unwritten rules

Unwritten rules

Use code that is already present

string

byte order functions

linked lists

typedef is evil

EVIL! EVIL! EVIL!It hides the real type of the variable

Allows programmers to get into trouble

large struct. on the stack

large struct. passed as return value

Can hid e long structure definition

pick a better name

typedef just signify a pointer type

could you be lazier?

Well, mostly...

Base system types

list_t

u8, u16, u64

Function pointer

No #ifdef in .c files

#ifdef belongs in .h file

Let your compiler do its work

Labeled elements in Initializers

Labeled elements in Initializers

Labeled elements in Initializers

Labeled elements in Initializers

Labeled elements in Initializers