sphinx.addnodesdocument)}( rawsource children](translations
LanguagesNode)}(hhh](h pending_xref)}(hhh]docutils.nodesTextChinese (Simplified)}parenthsba
attributes}(ids]classes]names]dupnames]backrefs] refdomainstdreftypedoc reftarget(/translations/zh_CN/process/coding-stylemodnameN classnameNrefexplicitutagnamehhhubh)}(hhh]hChinese (Traditional)}hh2sbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget(/translations/zh_TW/process/coding-stylemodnameN classnameNrefexplicituh1hhhubh)}(hhh]hItalian}hhFsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget(/translations/it_IT/process/coding-stylemodnameN classnameNrefexplicituh1hhhubh)}(hhh]hJapanese}hhZsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget(/translations/ja_JP/process/coding-stylemodnameN classnameNrefexplicituh1hhhubh)}(hhh]hKorean}hhnsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget(/translations/ko_KR/process/coding-stylemodnameN classnameNrefexplicituh1hhhubh)}(hhh]hSpanish}hhsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget(/translations/sp_SP/process/coding-stylemodnameN classnameNrefexplicituh1hhhubeh}(h]h ]h"]h$]h&]current_languageEnglishuh1h
hh _documenthsourceNlineNubhtarget)}(h.. _codingstyle:h]h}(h]h ]h"]h$]h&]refidcodingstyleuh1hhKhhhhhB/var/lib/git/docbuild/linux/Documentation/process/coding-style.rstubhsection)}(hhh](htitle)}(hLinux kernel coding styleh]hLinux kernel coding style}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhhhhhKubh paragraph)}(hXC This is a short document describing the preferred coding style for the
linux kernel. Coding style is very personal, and I won't **force** my
views on anybody, but this is what goes for anything that I have to be
able to maintain, and I'd prefer it for most other things too. Please
at least consider the points made here.h](hThis is a short document describing the preferred coding style for the
linux kernel. Coding style is very personal, and I won’t }(hhhhhNhNubhstrong)}(h **force**h]hforce}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhubh my
views on anybody, but this is what goes for anything that I have to be
able to maintain, and I’d prefer it for most other things too. Please
at least consider the points made here.}(hhhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhhhhubh)}(hFirst 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.h]hFirst 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.}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhhhhubh)}(hAnyway, here goes:h]hAnyway, here goes:}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhhhhubh)}(hhh](h)}(h1) Indentationh]h1) Indentation}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj hhhhhKubh)}(hTabs are 8 characters, and thus indentations are also 8 characters.
There are heretic movements that try to make indentations 4 (or even 2!)
characters deep, and that is akin to trying to define the value of PI to
be 3.h]hTabs are 8 characters, and thus indentations are also 8 characters.
There are heretic movements that try to make indentations 4 (or even 2!)
characters deep, and that is akin to trying to define the value of PI to
be 3.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj hhubh)}(hX Rationale: The whole idea behind indentation is to clearly define where
a block of control starts and ends. Especially when you've been looking
at your screen for 20 straight hours, you'll find it a lot easier to see
how the indentation works if you have large indentations.h]hX Rationale: The whole idea behind indentation is to clearly define where
a block of control starts and ends. Especially when you’ve been looking
at your screen for 20 straight hours, you’ll find it a lot easier to see
how the indentation works if you have large indentations.}(hj$ hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj hhubh)}(hX& Now, some people will claim that having 8-character indentations makes
the code move too far to the right, and makes it hard to read on a
80-character terminal screen. The answer to that is that if you need
more than 3 levels of indentation, you're screwed anyway, and should fix
your program.h]hX( Now, some people will claim that having 8-character indentations makes
the code move too far to the right, and makes it hard to read on a
80-character terminal screen. The answer to that is that if you need
more than 3 levels of indentation, you’re screwed anyway, and should fix
your program.}(hj2 hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj hhubh)}(hIn short, 8-char indents make things easier to read, and have the added
benefit of warning you when you're nesting your functions too deep.
Heed that warning.h]hIn short, 8-char indents make things easier to read, and have the added
benefit of warning you when you’re nesting your functions too deep.
Heed that warning.}(hj@ hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK%hj hhubh)}(hThe preferred way to ease multiple indentation levels in a switch statement is
to align the ``switch`` and its subordinate ``case`` labels in the same column
instead of ``double-indenting`` the ``case`` labels. E.g.:h](h\The preferred way to ease multiple indentation levels in a switch statement is
to align the }(hjN hhhNhNubhliteral)}(h
``switch``h]hswitch}(hjX hhhNhNubah}(h]h ]h"]h$]h&]uh1jV hjN ubh and its subordinate }(hjN hhhNhNubjW )}(h``case``h]hcase}(hjj hhhNhNubah}(h]h ]h"]h$]h&]uh1jV hjN ubh& labels in the same column
instead of }(hjN hhhNhNubjW )}(h``double-indenting``h]hdouble-indenting}(hj| hhhNhNubah}(h]h ]h"]h$]h&]uh1jV hjN ubh the }(hjN hhhNhNubjW )}(h``case``h]hcase}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jV hjN ubh labels. E.g.:}(hjN hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhK)hj hhubh
literal_block)}(hswitch (suffix) {
case 'G':
case 'g':
mem <<= 30;
break;
case 'M':
case 'm':
mem <<= 20;
break;
case 'K':
case 'k':
mem <<= 10;
fallthrough;
default:
break;
}h]hswitch (suffix) {
case 'G':
case 'g':
mem <<= 30;
break;
case 'M':
case 'm':
mem <<= 20;
break;
case 'K':
case 'k':
mem <<= 10;
fallthrough;
default:
break;
}}hj sbah}(h]h ]h"]h$]h&] xml:spacepreserveforcelanguagechighlight_args}uh1j hhhK-hj hhubh)}(hQDon't put multiple statements on a single line unless you have
something to hide:h]hSDon’t put multiple statements on a single line unless you have
something to hide:}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK@hj hhubj )}(h1if (condition) do_this;
do_something_everytime;h]h1if (condition) do_this;
do_something_everytime;}hj sbah}(h]h ]h"]h$]h&]j j j j j j }uh1j hhhKChj hhubh)}(h'Don't use commas to avoid using braces:h]h)Don’t use commas to avoid using braces:}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKHhj hhubj )}(h,if (condition)
do_this(), do_that();h]h,if (condition)
do_this(), do_that();}hj sbah}(h]h ]h"]h$]h&]j j j j j j }uh1j hhhKJhj hhubh)}(h+Always uses braces for multiple statements:h]h+Always uses braces for multiple statements:}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKOhj hhubj )}(h8if (condition) {
do_this();
do_that();
}h]h8if (condition) {
do_this();
do_that();
}}hj sbah}(h]h ]h"]h$]h&]j j j j j j }uh1j hhhKQhj hhubh)}(hxDon't put multiple assignments on a single line either. Kernel coding style
is super simple. Avoid tricky expressions.h]hzDon’t put multiple assignments on a single line either. Kernel coding style
is super simple. Avoid tricky expressions.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKXhj hhubh)}(hOutside of comments, documentation and except in Kconfig, spaces are never
used for indentation, and the above example is deliberately broken.h]hOutside of comments, documentation and except in Kconfig, spaces are never
used for indentation, and the above example is deliberately broken.}(hj" hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK\hj hhubh)}(hCGet a decent editor and don't leave whitespace at the end of lines.h]hEGet a decent editor and don’t leave whitespace at the end of lines.}(hj0 hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK_hj hhubeh}(h]indentationah ]h"]1) indentationah$]h&]uh1hhhhhhhhKubh)}(hhh](h)}(h"2) Breaking long lines and stringsh]h"2) Breaking long lines and strings}(hjI hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjF hhhhhKcubh)}(hYCoding style is all about readability and maintainability using commonly
available tools.h]hYCoding style is all about readability and maintainability using commonly
available tools.}(hjW hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKehjF hhubh)}(hAThe preferred limit on the length of a single line is 80 columns.h]hAThe preferred limit on the length of a single line is 80 columns.}(hje hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhhjF hhubh)}(hStatements longer than 80 columns should be broken into sensible chunks,
unless exceeding 80 columns significantly increases readability and does
not hide information.h]hStatements longer than 80 columns should be broken into sensible chunks,
unless exceeding 80 columns significantly increases readability and does
not hide information.}(hjs hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKjhjF hhubh)}(hDescendants are always substantially shorter than the parent and
are placed substantially to the right. A very commonly used style
is to align descendants to a function open parenthesis.h]hDescendants are always substantially shorter than the parent and
are placed substantially to the right. A very commonly used style
is to align descendants to a function open parenthesis.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKnhjF hhubh)}(hKThese same rules are applied to function headers with a long argument list.h]hKThese same rules are applied to function headers with a long argument list.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKrhjF hhubh)}(hsHowever, never break user-visible strings such as printk messages because
that breaks the ability to grep for them.h]hsHowever, never break user-visible strings such as printk messages because
that breaks the ability to grep for them.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKthjF hhubeh}(h]breaking-long-lines-and-stringsah ]h"]"2) breaking long lines and stringsah$]h&]uh1hhhhhhhhKcubh)}(hhh](h)}(h3) Placing Braces and Spacesh]h3) Placing Braces and Spaces}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj hhhhhKyubh)}(hX[ 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
choose one placement strategy over the other, but the preferred way, as
shown to us by the prophets Kernighan and Ritchie, is to put the opening
brace last on the line, and put the closing brace first, thusly:h]hX[ 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
choose one placement strategy over the other, but the preferred way, as
shown to us by the prophets Kernighan and Ritchie, is to put the opening
brace last on the line, and put the closing brace first, thusly:}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK{hj hhubj )}(h"if (x is true) {
we do y
}h]h"if (x is true) {
we do y
}}hj sbah}(h]h ]h"]h$]h&]j j j j j j }uh1j hhhKhj hhubh)}(hVThis applies to all non-function statement blocks (if, switch, for,
while, do). E.g.:h]hVThis applies to all non-function statement blocks (if, switch, for,
while, do). E.g.:}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj hhubj )}(hswitch (action) {
case KOBJ_ADD:
return "add";
case KOBJ_REMOVE:
return "remove";
case KOBJ_CHANGE:
return "change";
default:
return NULL;
}h]hswitch (action) {
case KOBJ_ADD:
return "add";
case KOBJ_REMOVE:
return "remove";
case KOBJ_CHANGE:
return "change";
default:
return NULL;
}}hj sbah}(h]h ]h"]h$]h&]j j j j j j }uh1j hhhKhj hhubh)}(hzHowever, there is one special case, namely functions: they have the
opening brace at the beginning of the next line, thus:h]hzHowever, there is one special case, namely functions: they have the
opening brace at the beginning of the next line, thus:}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj hhubj )}(h0int function(int x)
{
body of function
}h]h0int function(int x)
{
body of function
}}hj sbah}(h]h ]h"]h$]h&]j j j j j j }uh1j hhhKhj hhubh)}(hHeretic people all over the world have claimed that this inconsistency
is ... well ... inconsistent, but all right-thinking people know that
(a) K&R are **right** and (b) K&R are right. Besides, functions are
special anyway (you can't nest them in C).h](hHeretic people all over the world have claimed that this inconsistency
is ... well ... inconsistent, but all right-thinking people know that
(a) K&R are }(hj hhhNhNubh)}(h **right**h]hright}(hj# hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj ubh\ and (b) K&R are right. Besides, functions are
special anyway (you can’t nest them in C).}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhj hhubh)}(hNote that the closing brace is empty on a line of its own, **except** in
the cases where it is followed by a continuation of the same statement,
ie a ``while`` in a do-statement or an ``else`` in an if-statement, like
this:h](h;Note that the closing brace is empty on a line of its own, }(hj; hhhNhNubh)}(h
**except**h]hexcept}(hjC hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj; ubhQ in
the cases where it is followed by a continuation of the same statement,
ie a }(hj; hhhNhNubjW )}(h ``while``h]hwhile}(hjU hhhNhNubah}(h]h ]h"]h$]h&]uh1jV hj; ubh in a do-statement or an }(hj; hhhNhNubjW )}(h``else``h]helse}(hjg hhhNhNubah}(h]h ]h"]h$]h&]uh1jV hj; ubh in an if-statement, like
this:}(hj; hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhj hhubj )}(h1do {
body of do-loop
} while (condition);h]h1do {
body of do-loop
} while (condition);}hj sbah}(h]h ]h"]h$]h&]j j j j j j }uh1j hhhKhj hhubh)}(handh]hand}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj hhubj )}(hPif (x == y) {
..
} else if (x > y) {
...
} else {
....
}h]hPif (x == y) {
..
} else if (x > y) {
...
} else {
....
}}hj sbah}(h]h ]h"]h$]h&]j j j j j j }uh1j hhhKhj hhubh)}(hRationale: K&R.h]hRationale: K&R.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj hhubh)}(hX# Also, note that this brace-placement also minimizes the number of empty
(or almost empty) lines, without any loss of readability. Thus, as the
supply of new-lines on your screen is not a renewable resource (think
25-line terminal screens here), you have more empty lines to put
comments on.h]hX# Also, note that this brace-placement also minimizes the number of empty
(or almost empty) lines, without any loss of readability. Thus, as the
supply of new-lines on your screen is not a renewable resource (think
25-line terminal screens here), you have more empty lines to put
comments on.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj hhubh)}(hADo not unnecessarily use braces where a single statement will do.h]hADo not unnecessarily use braces where a single statement will do.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj hhubj )}(h if (condition)
action();h]h if (condition)
action();}hj sbah}(h]h ]h"]h$]h&]j j j j j j }uh1j hhhKhj hhubh)}(handh]hand}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj hhubj )}(h9if (condition)
do_this();
else
do_that();h]h9if (condition)
do_this();
else
do_that();}hj sbah}(h]h ]h"]h$]h&]j j j j j j }uh1j hhhKhj hhubh)}(hThis does not apply if only one branch of a conditional statement is a single
statement; in the latter case use braces in both branches:h]hThis does not apply if only one branch of a conditional statement is a single
statement; in the latter case use braces in both branches:}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj hhubj )}(hVif (condition) {
do_this();
do_that();
} else {
otherwise();
}h]hVif (condition) {
do_this();
do_that();
} else {
otherwise();
}}hj sbah}(h]h ]h"]h$]h&]j j j j j j }uh1j hhhKhj hhubh)}(hJAlso, use braces when a loop contains more than a single simple statement:h]hJAlso, use braces when a loop contains more than a single simple statement:}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj hhubj )}(hGwhile (condition) {
if (test)
do_something();
}h]hGwhile (condition) {
if (test)
do_something();
}}hj, sbah}(h]h ]h"]h$]h&]j j j j j j }uh1j hhhKhj hhubh)}(hhh](h)}(h3.1) Spacesh]h3.1) Spaces}(hj> hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj; hhhhhKubh)}(hX Linux kernel style for use of spaces depends (mostly) on
function-versus-keyword usage. Use a space after (most) keywords. The
notable exceptions are sizeof, typeof, alignof, and __attribute__, which look
somewhat like functions (and are usually used with parentheses in Linux,
although they are not required in the language, as in: ``sizeof info`` after
``struct fileinfo info;`` is declared).h](hXO Linux kernel style for use of spaces depends (mostly) on
function-versus-keyword usage. Use a space after (most) keywords. The
notable exceptions are sizeof, typeof, alignof, and __attribute__, which look
somewhat like functions (and are usually used with parentheses in Linux,
although they are not required in the language, as in: }(hjL hhhNhNubjW )}(h``sizeof info``h]hsizeof info}(hjT hhhNhNubah}(h]h ]h"]h$]h&]uh1jV hjL ubh after
}(hjL hhhNhNubjW )}(h``struct fileinfo info;``h]hstruct fileinfo info;}(hjf hhhNhNubah}(h]h ]h"]h$]h&]uh1jV hjL ubh is declared).}(hjL hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhj; hhubh)}(h%So use a space after these keywords::h]h$So use a space after these keywords:}(hj~ hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj; hhubj )}(h if, switch, case, for, do, whileh]h if, switch, case, for, do, while}hj sbah}(h]h ]h"]h$]h&]j j uh1j hhhKhj; hhubh)}(h>but not with sizeof, typeof, alignof, or __attribute__. E.g.,h]h>but not with sizeof, typeof, alignof, or __attribute__. E.g.,}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj; hhubj )}(hs = sizeof(struct file);h]hs = sizeof(struct file);}hj sbah}(h]h ]h"]h$]h&]j j j j j j }uh1j hhhKhj; hhubh)}(hVDo not add spaces around (inside) parenthesized expressions. This example is
**bad**:h](hNDo not add spaces around (inside) parenthesized expressions. This example is
}(hj hhhNhNubh)}(h**bad**h]hbad}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj ubh:}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhj; hhubj )}(hs = sizeof( struct file );h]hs = sizeof( struct file );}hj sbah}(h]h ]h"]h$]h&]j j j j j j }uh1j hhhMhj; hhubh)}(hWhen declaring pointer data or a function that returns a pointer type, the
preferred use of ``*`` is adjacent to the data name or function name and not
adjacent to the type name. Examples:h](h\When declaring pointer data or a function that returns a pointer type, the
preferred use of }(hj hhhNhNubjW )}(h``*``h]h*}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jV hj ubh\ is adjacent to the data name or function name and not
adjacent to the type name. Examples:}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhj; hhubj )}(hnchar *linux_banner;
unsigned long long memparse(char *ptr, char **retptr);
char *match_strdup(substring_t *s);h]hnchar *linux_banner;
unsigned long long memparse(char *ptr, char **retptr);
char *match_strdup(substring_t *s);}hj sbah}(h]h ]h"]h$]h&]j j j j j j }uh1j hhhMhj; hhubh)}(h`Use one space around (on each side of) most binary and ternary operators,
such as any of these::h]h_Use one space around (on each side of) most binary and ternary operators,
such as any of these:}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj; hhubj )}(h5= + - < > * / % | & ^ <= >= == != ? :h]h5= + - < > * / % | & ^ <= >= == != ? :}hj# sbah}(h]h ]h"]h$]h&]j j uh1j hhhMhj; hhubh)}(h$but no space after unary operators::h]h#but no space after unary operators:}(hj1 hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj; hhubj )}(hA& * + - ~ ! sizeof typeof alignof __attribute__ definedh]hA& * + - ~ ! sizeof typeof alignof __attribute__ defined}hj? sbah}(h]h ]h"]h$]h&]j j uh1j hhhMhj; hhubh)}(hCno space before the postfix increment & decrement unary operators::h]hBno space before the postfix increment & decrement unary operators:}(hjM hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj; hhubj )}(h++ --h]h++ --}hj[ sbah}(h]h ]h"]h$]h&]j j uh1j hhhMhj; hhubh)}(hAno space after the prefix increment & decrement unary operators::h]h@no space after the prefix increment & decrement unary operators:}(hji hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj; hhubj )}(h++ --h]h++ --}hjw sbah}(h]h ]h"]h$]h&]j j uh1j hhhM!hj; hhubh)}(hDand no space around the ``.`` and ``->`` structure member operators.h](hand no space around the }(hj hhhNhNubjW )}(h``.``h]h.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jV hj ubh and }(hj hhhNhNubjW )}(h``->``h]h->}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jV hj ubh structure member operators.}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhM#hj; hhubh)}(hX Do not leave trailing whitespace at the ends of lines. Some editors with
``smart`` indentation will insert whitespace at the beginning of new lines as
appropriate, so you can start typing the next line of code right away.
However, some such editors do not remove the whitespace if you end up not
putting a line of code there, such as if you leave a blank line. As a result,
you end up with lines containing trailing whitespace.h](hJDo not leave trailing whitespace at the ends of lines. Some editors with
}(hj hhhNhNubjW )}(h ``smart``h]hsmart}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jV hj ubhXZ indentation will insert whitespace at the beginning of new lines as
appropriate, so you can start typing the next line of code right away.
However, some such editors do not remove the whitespace if you end up not
putting a line of code there, such as if you leave a blank line. As a result,
you end up with lines containing trailing whitespace.}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhM%hj; hhubh)}(hGit will warn you about patches that introduce trailing whitespace, and can
optionally strip the trailing whitespace for you; however, if applying a series
of patches, this may make later patches in the series fail by changing their
context lines.h]hGit will warn you about patches that introduce trailing whitespace, and can
optionally strip the trailing whitespace for you; however, if applying a series
of patches, this may make later patches in the series fail by changing their
context lines.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM,hj; hhubeh}(h]spacesah ]h"]3.1) spacesah$]h&]uh1hhj hhhhhKubeh}(h]placing-braces-and-spacesah ]h"]3) placing braces and spacesah$]h&]uh1hhhhhhhhKyubh)}(hhh](h)}(h 4) Namingh]h 4) Naming}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj hhhhhM3ubh)}(hX: C is a Spartan language, and your naming conventions should follow suit.
Unlike Modula-2 and Pascal programmers, C programmers do not use cute
names like ThisVariableIsATemporaryCounter. A C programmer would call that
variable ``tmp``, which is much easier to write, and not the least more
difficult to understand.h](hC is a Spartan language, and your naming conventions should follow suit.
Unlike Modula-2 and Pascal programmers, C programmers do not use cute
names like ThisVariableIsATemporaryCounter. A C programmer would call that
variable }(hj hhhNhNubjW )}(h``tmp``h]htmp}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jV hj ubhP, which is much easier to write, and not the least more
difficult to understand.}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhM5hj hhubh)}(hHOWEVER, while mixed-case names are frowned upon, descriptive names for
global variables are a must. To call a global function ``foo`` is a
shooting offense.h](hHOWEVER, while mixed-case names are frowned upon, descriptive names for
global variables are a must. To call a global function }(hj& hhhNhNubjW )}(h``foo``h]hfoo}(hj. hhhNhNubah}(h]h ]h"]h$]h&]uh1jV hj& ubh is a
shooting offense.}(hj& hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhM;hj hhubh)}(hX GLOBAL variables (to be used only if you **really** need them) need to
have descriptive names, as do global functions. If you have a function
that counts the number of active users, you should call that
``count_active_users()`` or similar, you should **not** call it ``cntusr()``.h](h)GLOBAL variables (to be used only if you }(hjF hhhNhNubh)}(h
**really**h]hreally}(hjN hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjF ubh need them) need to
have descriptive names, as do global functions. If you have a function
that counts the number of active users, you should call that
}(hjF hhhNhNubjW )}(h``count_active_users()``h]hcount_active_users()}(hj` hhhNhNubah}(h]h ]h"]h$]h&]uh1jV hjF ubh or similar, you should }(hjF hhhNhNubh)}(h**not**h]hnot}(hjr hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjF ubh call it }(hjF hhhNhNubjW )}(h``cntusr()``h]hcntusr()}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jV hjF ubh.}(hjF hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhM?hj hhubh)}(hEncoding the type of a function into the name (so-called Hungarian
notation) is asinine - the compiler knows the types anyway and can check
those, and it only confuses the programmer.h]hEncoding the type of a function into the name (so-called Hungarian
notation) is asinine - the compiler knows the types anyway and can check
those, and it only confuses the programmer.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMDhj hhubh)}(hXN LOCAL variable names should be short, and to the point. If you have
some random integer loop counter, it should probably be called ``i``.
Calling it ``loop_counter`` is non-productive, if there is no chance of it
being mis-understood. Similarly, ``tmp`` can be just about any type of
variable that is used to hold a temporary value.h](hLOCAL variable names should be short, and to the point. If you have
some random integer loop counter, it should probably be called }(hj hhhNhNubjW )}(h``i``h]hi}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jV hj ubh
.
Calling it }(hj hhhNhNubjW )}(h``loop_counter``h]hloop_counter}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jV hj ubhR is non-productive, if there is no chance of it
being mis-understood. Similarly, }(hj hhhNhNubjW )}(h``tmp``h]htmp}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jV hj ubhO can be just about any type of
variable that is used to hold a temporary value.}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMHhj hhubh)}(hIf you are afraid to mix up your local variable names, you have another
problem, which is called the function-growth-hormone-imbalance syndrome.
See chapter 6 (Functions).h]hIf you are afraid to mix up your local variable names, you have another
problem, which is called the function-growth-hormone-imbalance syndrome.
See chapter 6 (Functions).}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMNhj hhubh)}(hFor symbol names and documentation, avoid introducing new usage of
'master / slave' (or 'slave' independent of 'master') and 'blacklist /
whitelist'.h]hFor symbol names and documentation, avoid introducing new usage of
‘master / slave’ (or ‘slave’ independent of ‘master’) and ‘blacklist /
whitelist’.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMRhj hhubhdefinition_list)}(hhh](hdefinition_list_item)}(hRecommended replacements for 'master / slave' are:
'{primary,main} / {secondary,replica,subordinate}'
'{initiator,requester} / {target,responder}'
'{controller,host} / {device,worker,proxy}'
'leader / follower'
'director / performer'
h](hterm)}(h2Recommended replacements for 'master / slave' are:h]h6Recommended replacements for ‘master / slave’ are:}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1j hhhM[hj ubh
definition)}(hhh]h)}(h'{primary,main} / {secondary,replica,subordinate}'
'{initiator,requester} / {target,responder}'
'{controller,host} / {device,worker,proxy}'
'leader / follower'
'director / performer'h]h‘{primary,main} / {secondary,replica,subordinate}’
‘{initiator,requester} / {target,responder}’
‘{controller,host} / {device,worker,proxy}’
‘leader / follower’
‘director / performer’}(hj* hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMWhj' ubah}(h]h ]h"]h$]h&]uh1j% hj ubeh}(h]h ]h"]h$]h&]uh1j hhhM[hj ubj )}(hfRecommended replacements for 'blacklist/whitelist' are:
'denylist / allowlist'
'blocklist / passlist'
h](j )}(h7Recommended replacements for 'blacklist/whitelist' are:h]h;Recommended replacements for ‘blacklist/whitelist’ are:}(hjH hhhNhNubah}(h]h ]h"]h$]h&]uh1j hhhM_hjD ubj& )}(hhh]h)}(h-'denylist / allowlist'
'blocklist / passlist'h]h5‘denylist / allowlist’
‘blocklist / passlist’}(hjY hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM^hjV ubah}(h]h ]h"]h$]h&]uh1j% hjD ubeh}(h]h ]h"]h$]h&]uh1j hhhM_hj hhubeh}(h]h ]h"]h$]h&]uh1j
hj hhhhhNubh)}(hX/ Exceptions for introducing new usage is to maintain a userspace ABI/API,
or when updating code for an existing (as of 2020) hardware or protocol
specification that mandates those terms. For new specifications
translate specification usage of the terminology to the kernel coding
standard where possible.h]hX/ Exceptions for introducing new usage is to maintain a userspace ABI/API,
or when updating code for an existing (as of 2020) hardware or protocol
specification that mandates those terms. For new specifications
translate specification usage of the terminology to the kernel coding
standard where possible.}(hjy hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMahj hhubeh}(h]namingah ]h"] 4) namingah$]h&]uh1hhhhhhhhM3ubh)}(hhh](h)}(h5) Typedefsh]h5) Typedefs}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj hhhhhMhubh)}(huPlease don't use things like ``vps_t``.
It's a **mistake** to use typedef for structures and pointers. When you see ah](hPlease don’t use things like }(hj hhhNhNubjW )}(h ``vps_t``h]hvps_t}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jV hj ubh.
It’s a }(hj hhhNhNubh)}(h**mistake**h]hmistake}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj ubh; to use typedef for structures and pointers. When you see a}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMjhj hhubj )}(hvps_t a;h]hvps_t a;}hj sbah}(h]h ]h"]h$]h&]j j j j j j }uh1j hhhMmhj hhubh)}(h9in the source, what does it mean?
In contrast, if it saysh]h9in the source, what does it mean?
In contrast, if it says}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMrhj hhubj )}(hstruct virtual_container *a;h]hstruct virtual_container *a;}hj sbah}(h]h ]h"]h$]h&]j j j j j j }uh1j hhhMuhj hhubh)}(h$you can actually tell what ``a`` is.h](hyou can actually tell what }(hj hhhNhNubjW )}(h``a``h]ha}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jV hj ubh is.}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMyhj hhubh)}(hZLots of people think that typedefs ``help readability``. Not so. They are
useful only for:h](h#Lots of people think that typedefs }(hj hhhNhNubjW )}(h``help readability``h]hhelp readability}(hj& hhhNhNubah}(h]h ]h"]h$]h&]uh1jV hj ubh#. Not so. They are
useful only for:}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhM{hj hhubhblock_quote)}(hX (a) totally opaque objects (where the typedef is actively used to **hide**
what the object is).
Example: ``pte_t`` etc. opaque objects that you can only access using
the proper accessor functions.
.. note::
Opaqueness and ``accessor functions`` are not good in themselves.
The reason we have them for things like pte_t etc. is that there
really is absolutely **zero** portably accessible information there.
(b) Clear integer types, where the abstraction **helps** avoid confusion
whether it is ``int`` or ``long``.
u8/u16/u32 are perfectly fine typedefs, although they fit into
category (d) better than here.
.. note::
Again - there needs to be a **reason** for this. If something is
``unsigned long``, then there's no reason to do
typedef unsigned long myflags_t;
but if there is a clear reason for why it under certain circumstances
might be an ``unsigned int`` and under other configurations might be
``unsigned long``, then by all means go ahead and use a typedef.
(c) when you use sparse to literally create a **new** type for
type-checking.
(d) New types which are identical to standard C99 types, in certain
exceptional circumstances.
Although it would only take a short amount of time for the eyes and
brain to become accustomed to the standard types like ``uint32_t``,
some people object to their use anyway.
Therefore, the Linux-specific ``u8/u16/u32/u64`` types and their
signed equivalents which are identical to standard types are
permitted -- although they are not mandatory in new code of your
own.
When editing existing code which already uses one or the other set
of types, you should conform to the existing choices in that code.
(e) Types safe for use in userspace.
In certain structures which are visible to userspace, we cannot
require C99 types and cannot use the ``u32`` form above. Thus, we
use __u32 and similar types in all structures which are shared
with userspace.
h]henumerated_list)}(hhh](h list_item)}(hX totally opaque objects (where the typedef is actively used to **hide**
what the object is).
Example: ``pte_t`` etc. opaque objects that you can only access using
the proper accessor functions.
.. note::
Opaqueness and ``accessor functions`` are not good in themselves.
The reason we have them for things like pte_t etc. is that there
really is absolutely **zero** portably accessible information there.
h](h)}(h[totally opaque objects (where the typedef is actively used to **hide**
what the object is).h](h>totally opaque objects (where the typedef is actively used to }(hjO hhhNhNubh)}(h**hide**h]hhide}(hjW hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjO ubh
what the object is).}(hjO hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhM~hjK ubh)}(hdExample: ``pte_t`` etc. opaque objects that you can only access using
the proper accessor functions.h](h Example: }(hjo hhhNhNubjW )}(h ``pte_t``h]hpte_t}(hjw hhhNhNubah}(h]h ]h"]h$]h&]uh1jV hjo ubhR etc. opaque objects that you can only access using
the proper accessor functions.}(hjo hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjK ubhnote)}(hOpaqueness and ``accessor functions`` are not good in themselves.
The reason we have them for things like pte_t etc. is that there
really is absolutely **zero** portably accessible information there.h]h)}(hOpaqueness and ``accessor functions`` are not good in themselves.
The reason we have them for things like pte_t etc. is that there
really is absolutely **zero** portably accessible information there.h](hOpaqueness and }(hj hhhNhNubjW )}(h``accessor functions``h]haccessor functions}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jV hj ubhs are not good in themselves.
The reason we have them for things like pte_t etc. is that there
really is absolutely }(hj hhhNhNubh)}(h**zero**h]hzero}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj ubh' portably accessible information there.}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhj ubah}(h]h ]h"]h$]h&]uh1j hjK ubeh}(h]h ]h"]h$]h&]uh1jI hjF ubjJ )}(hX: Clear integer types, where the abstraction **helps** avoid confusion
whether it is ``int`` or ``long``.
u8/u16/u32 are perfectly fine typedefs, although they fit into
category (d) better than here.
.. note::
Again - there needs to be a **reason** for this. If something is
``unsigned long``, then there's no reason to do
typedef unsigned long myflags_t;
but if there is a clear reason for why it under certain circumstances
might be an ``unsigned int`` and under other configurations might be
``unsigned long``, then by all means go ahead and use a typedef.
h](h)}(hgClear integer types, where the abstraction **helps** avoid confusion
whether it is ``int`` or ``long``.h](h+Clear integer types, where the abstraction }(hj hhhNhNubh)}(h **helps**h]hhelps}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj ubh avoid confusion
whether it is }(hj hhhNhNubjW )}(h``int``h]hint}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jV hj ubh or }(hj hhhNhNubjW )}(h``long``h]hlong}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jV hj ubh.}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhj ubh)}(h]u8/u16/u32 are perfectly fine typedefs, although they fit into
category (d) better than here.h]h]u8/u16/u32 are perfectly fine typedefs, although they fit into
category (d) better than here.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj ubj )}(hAgain - there needs to be a **reason** for this. If something is
``unsigned long``, then there's no reason to do
typedef unsigned long myflags_t;h](h)}(hpAgain - there needs to be a **reason** for this. If something is
``unsigned long``, then there's no reason to doh](hAgain - there needs to be a }(hj- hhhNhNubh)}(h
**reason**h]hreason}(hj5 hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj- ubh for this. If something is
}(hj- hhhNhNubjW )}(h``unsigned long``h]h
unsigned long}(hjG hhhNhNubah}(h]h ]h"]h$]h&]uh1jV hj- ubh , then there’s no reason to do}(hj- hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhj) ubj? )}(h typedef unsigned long myflags_t;h]h)}(hja h]h typedef unsigned long myflags_t;}(hjc hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj_ ubah}(h]h ]h"]h$]h&]uh1j> hhhMhj) ubeh}(h]h ]h"]h$]h&]uh1j hj ubh)}(hbut if there is a clear reason for why it under certain circumstances
might be an ``unsigned int`` and under other configurations might be
``unsigned long``, then by all means go ahead and use a typedef.h](hRbut if there is a clear reason for why it under certain circumstances
might be an }(hj| hhhNhNubjW )}(h``unsigned int``h]hunsigned int}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jV hj| ubh) and under other configurations might be
}(hj| hhhNhNubjW )}(h``unsigned long``h]h
unsigned long}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jV hj| ubh/, then by all means go ahead and use a typedef.}(hj| hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhj ubeh}(h]h ]h"]h$]h&]uh1jI hjF ubjJ )}(hJwhen you use sparse to literally create a **new** type for
type-checking.
h]h)}(hIwhen you use sparse to literally create a **new** type for
type-checking.h](h*when you use sparse to literally create a }(hj hhhNhNubh)}(h**new**h]hnew}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj ubh type for
type-checking.}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhj ubah}(h]h ]h"]h$]h&]uh1jI hjF ubjJ )}(hXX New types which are identical to standard C99 types, in certain
exceptional circumstances.
Although it would only take a short amount of time for the eyes and
brain to become accustomed to the standard types like ``uint32_t``,
some people object to their use anyway.
Therefore, the Linux-specific ``u8/u16/u32/u64`` types and their
signed equivalents which are identical to standard types are
permitted -- although they are not mandatory in new code of your
own.
When editing existing code which already uses one or the other set
of types, you should conform to the existing choices in that code.
h](h)}(hZNew types which are identical to standard C99 types, in certain
exceptional circumstances.h]hZNew types which are identical to standard C99 types, in certain
exceptional circumstances.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj ubh)}(hAlthough it would only take a short amount of time for the eyes and
brain to become accustomed to the standard types like ``uint32_t``,
some people object to their use anyway.h](hzAlthough it would only take a short amount of time for the eyes and
brain to become accustomed to the standard types like }(hj hhhNhNubjW )}(h``uint32_t``h]huint32_t}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jV hj ubh),
some people object to their use anyway.}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhj ubh)}(hTherefore, the Linux-specific ``u8/u16/u32/u64`` types and their
signed equivalents which are identical to standard types are
permitted -- although they are not mandatory in new code of your
own.h](hTherefore, the Linux-specific }(hj
hhhNhNubjW )}(h``u8/u16/u32/u64``h]hu8/u16/u32/u64}(hj
hhhNhNubah}(h]h ]h"]h$]h&]uh1jV hj
ubh types and their
signed equivalents which are identical to standard types are
permitted -- although they are not mandatory in new code of your
own.}(hj
hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhj ubh)}(hWhen editing existing code which already uses one or the other set
of types, you should conform to the existing choices in that code.h]hWhen editing existing code which already uses one or the other set
of types, you should conform to the existing choices in that code.}(hj0
hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj ubeh}(h]h ]h"]h$]h&]uh1jI hjF ubjJ )}(hTypes safe for use in userspace.
In certain structures which are visible to userspace, we cannot
require C99 types and cannot use the ``u32`` form above. Thus, we
use __u32 and similar types in all structures which are shared
with userspace.
h](h)}(h Types safe for use in userspace.h]h Types safe for use in userspace.}(hjH
hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjD
ubh)}(hIn certain structures which are visible to userspace, we cannot
require C99 types and cannot use the ``u32`` form above. Thus, we
use __u32 and similar types in all structures which are shared
with userspace.h](heIn certain structures which are visible to userspace, we cannot
require C99 types and cannot use the }(hjV
hhhNhNubjW )}(h``u32``h]hu32}(hj^
hhhNhNubah}(h]h ]h"]h$]h&]uh1jV hjV
ubhd form above. Thus, we
use __u32 and similar types in all structures which are shared
with userspace.}(hjV
hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjD
ubeh}(h]h ]h"]h$]h&]uh1jI hjF ubeh}(h]h ]h"]h$]h&]enumtype
loweralphaprefix(suffix)uh1jD hj@ ubah}(h]h ]h"]h$]h&]uh1j> hhhM~hj hhubh)}(hMaybe there are other cases too, but the rule should basically be to NEVER
EVER use a typedef unless you can clearly match one of those rules.h]hMaybe there are other cases too, but the rule should basically be to NEVER
EVER use a typedef unless you can clearly match one of those rules.}(hj
hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj hhubh)}(h|In general, a pointer, or a struct that has elements that can reasonably
be directly accessed should **never** be a typedef.h](heIn general, a pointer, or a struct that has elements that can reasonably
be directly accessed should }(hj
hhhNhNubh)}(h **never**h]hnever}(hj
hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj
ubh be a typedef.}(hj
hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhj hhubeh}(h]typedefsah ]h"]5) typedefsah$]h&]uh1hhhhhhhhMhubh)}(hhh](h)}(h6) Functionsh]h6) Functions}(hj
hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj
hhhhhMubh)}(hFunctions should be short and sweet, and do just one thing. They should
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.h]hFunctions should be short and sweet, and do just one thing. They should
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.}(hj
hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj
hhubh)}(hXB The maximum length of a function is inversely proportional to the
complexity and indentation level of that function. So, if you have a
conceptually simple function that is just one long (but simple)
case-statement, where you have to do lots of small things for a lot of
different cases, it's OK to have a longer function.h]hXD The maximum length of a function is inversely proportional to the
complexity and indentation level of that function. So, if you have a
conceptually simple function that is just one long (but simple)
case-statement, where you have to do lots of small things for a lot of
different cases, it’s OK to have a longer function.}(hj
hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj
hhubh)}(hX However, if you have a complex function, and you suspect that a
less-than-gifted first-year high-school student might not even
understand what the function is all about, you should adhere to the
maximum limits all the more closely. Use helper functions with
descriptive names (you can ask the compiler to in-line them if you think
it's performance-critical, and it will probably do a better job of it
than you would have done).h]hX However, if you have a complex function, and you suspect that a
less-than-gifted first-year high-school student might not even
understand what the function is all about, you should adhere to the
maximum limits all the more closely. Use helper functions with
descriptive names (you can ask the compiler to in-line them if you think
it’s performance-critical, and it will probably do a better job of it
than you would have done).}(hj
hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj
hhubh)}(hX Another measure of the function is the number of local variables. They
shouldn't exceed 5-10, or you're doing something wrong. Re-think the
function, and split it into smaller pieces. A human brain can
generally easily keep track of about 7 different things, anything more
and it gets confused. You know you're brilliant, but maybe you'd like
to understand what you did 2 weeks from now.h]hX Another measure of the function is the number of local variables. They
shouldn’t exceed 5-10, or you’re doing something wrong. Re-think the
function, and split it into smaller pieces. A human brain can
generally easily keep track of about 7 different things, anything more
and it gets confused. You know you’re brilliant, but maybe you’d like
to understand what you did 2 weeks from now.}(hj
hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj
hhubh)}(hIn source files, separate functions with one blank line. If the function is
exported, the **EXPORT** macro for it should follow immediately after the
closing function brace line. E.g.:h](h[In source files, separate functions with one blank line. If the function is
exported, the }(hj
hhhNhNubh)}(h
**EXPORT**h]hEXPORT}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj
ubhU macro for it should follow immediately after the
closing function brace line. E.g.:}(hj
hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhj
hhubj )}(hfint system_is_up(void)
{
return system_state == SYSTEM_RUNNING;
}
EXPORT_SYMBOL(system_is_up);h]hfint system_is_up(void)
{
return system_state == SYSTEM_RUNNING;
}
EXPORT_SYMBOL(system_is_up);}hj- sbah}(h]h ]h"]h$]h&]j j j j j j }uh1j hhhMhj
hhubh)}(hhh](h)}(h6.1) Function prototypesh]h6.1) Function prototypes}(hj? hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj< hhhhhMubh)}(hIn function prototypes, include parameter names with their data types.
Although this is not required by the C language, it is preferred in Linux
because it is a simple way to add valuable information for the reader.h]hIn function prototypes, include parameter names with their data types.
Although this is not required by the C language, it is preferred in Linux
because it is a simple way to add valuable information for the reader.}(hjM hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj< hhubh)}(huDo not use the ``extern`` keyword with function declarations as this makes
lines longer and isn't strictly necessary.h](hDo not use the }(hj[ hhhNhNubjW )}(h
``extern``h]hextern}(hjc hhhNhNubah}(h]h ]h"]h$]h&]uh1jV hj[ ubh^ keyword with function declarations as this makes
lines longer and isn’t strictly necessary.}(hj[ hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhj< hhubh)}(hWhen writing function prototypes, please keep the `order of elements regular
`_.
For example, using this function declaration example::h](h2When writing function prototypes, please keep the }(hj{ hhhNhNubh reference)}(h`order of elements regular
`_h]horder of elements regular}(hj hhhNhNubah}(h]h ]h"]h$]h&]nameorder of elements regularrefurifhttps://lore.kernel.org/mm-commits/CAHk-=wiOCLRny5aifWNhr621kYrJwhfURsa0vFPeUEm8mF0ufg@mail.gmail.com/uh1j hj{ ubh)}(hi
h]h}(h]order-of-elements-regularah ]h"]order of elements regularah$]h&]refurij uh1h
referencedKhj{ ubh7.
For example, using this function declaration example:}(hj{ hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhj< hhubj )}(h__init void * __must_check action(enum magic value, size_t size, u8 count,
char *fmt, ...) __printf(4, 5) __malloc;h]h__init void * __must_check action(enum magic value, size_t size, u8 count,
char *fmt, ...) __printf(4, 5) __malloc;}hj sbah}(h]h ]h"]h$]h&]j j uh1j hhhMhj< hhubh)}(h