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]hPortuguese (Brazilian)}hhsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget(/translations/pt_BR/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:}(hj hhhNhNubah}(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.}(hj8 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.}(hjF 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.}(hjT 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 }(hjb hhhNhNubhliteral)}(h
``switch``h]hswitch}(hjl hhhNhNubah}(h]h ]h"]h$]h&]uh1jj hjb ubh and its subordinate }(hjb hhhNhNubjk )}(h``case``h]hcase}(hj~ hhhNhNubah}(h]h ]h"]h$]h&]uh1jj hjb ubh& labels in the same column
instead of }(hjb hhhNhNubjk )}(h``double-indenting``h]hdouble-indenting}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jj hjb ubh the }(hjb hhhNhNubjk )}(h``case``h]hcase}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jj hjb ubh labels. E.g.:}(hjb 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 use braces for multiple statements:h]h*Always use 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.}(hj6 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.}(hjD 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}(hj] hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjZ 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.}(hjk hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKehjZ 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.}(hjy hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhhjZ 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.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKjhjZ 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&]uh1hhhhKnhjZ 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&]uh1hhhhKrhjZ 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&]uh1hhhhKthjZ 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}(hj7 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, }(hjO hhhNhNubh)}(h
**except**h]hexcept}(hjW hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjO ubhQ in
the cases where it is followed by a continuation of the same statement,
ie a }(hjO hhhNhNubjk )}(h ``while``h]hwhile}(hji hhhNhNubah}(h]h ]h"]h$]h&]uh1jj hjO ubh in a do-statement or an }(hjO hhhNhNubjk )}(h``else``h]helse}(hj{ hhhNhNubah}(h]h ]h"]h$]h&]uh1jj hjO ubh in an if-statement, like
this:}(hjO 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:}(hj2 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}(hjR hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjO 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: }(hj` hhhNhNubjk )}(h``sizeof info``h]hsizeof info}(hjh hhhNhNubah}(h]h ]h"]h$]h&]uh1jj hj` ubh after
}(hj` hhhNhNubjk )}(h``struct fileinfo info;``h]hstruct fileinfo info;}(hjz hhhNhNubah}(h]h ]h"]h$]h&]uh1jj hj` ubh is declared).}(hj` hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjO 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&]uh1hhhhKhjO 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 hhhKhjO 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&]uh1hhhhKhjO hhubj )}(hs = sizeof(struct file);h]hs = sizeof(struct file);}hj sbah}(h]h ]h"]h$]h&]j j j j j j }uh1j hhhKhjO 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&]uh1hhhhKhjO hhubj )}(hs = sizeof( struct file );h]hs = sizeof( struct file );}hj sbah}(h]h ]h"]h$]h&]j j j j j j }uh1j hhhMhjO 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 hhhNhNubjk )}(h``*``h]h*}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jj 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&]uh1hhhhMhjO 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 hhhMhjO 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&]uh1hhhhMhjO hhubj )}(h5= + - < > * / % | & ^ <= >= == != ? :h]h5= + - < > * / % | & ^ <= >= == != ? :}hj7 sbah}(h]h ]h"]h$]h&]j j uh1j hhhMhjO hhubh)}(h$but no space after unary operators::h]h#but no space after unary operators:}(hjE hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjO hhubj )}(hA& * + - ~ ! sizeof typeof alignof __attribute__ definedh]hA& * + - ~ ! sizeof typeof alignof __attribute__ defined}hjS sbah}(h]h ]h"]h$]h&]j j uh1j hhhMhjO hhubh)}(hCno space before the postfix increment & decrement unary operators::h]hBno space before the postfix increment & decrement unary operators:}(hja hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjO hhubj )}(h++ --h]h++ --}hjo sbah}(h]h ]h"]h$]h&]j j uh1j hhhMhjO hhubh)}(hAno space after the prefix increment & decrement unary operators::h]h@no space after the prefix increment & decrement unary operators:}(hj} hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjO hhubj )}(h++ --h]h++ --}hj sbah}(h]h ]h"]h$]h&]j j uh1j hhhM!hjO hhubh)}(hDand no space around the ``.`` and ``->`` structure member operators.h](hand no space around the }(hj hhhNhNubjk )}(h``.``h]h.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jj hj ubh and }(hj hhhNhNubjk )}(h``->``h]h->}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jj hj ubh structure member operators.}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhM#hjO 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 hhhNhNubjk )}(h ``smart``h]hsmart}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jj 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%hjO 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,hjO 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 hhhNhNubjk )}(h``tmp``h]htmp}(hj" hhhNhNubah}(h]h ]h"]h$]h&]uh1jj 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: hhhNhNubjk )}(h``foo``h]hfoo}(hjB hhhNhNubah}(h]h ]h"]h$]h&]uh1jj 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 }(hjZ hhhNhNubh)}(h
**really**h]hreally}(hjb hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjZ 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
}(hjZ hhhNhNubjk )}(h``count_active_users()``h]hcount_active_users()}(hjt hhhNhNubah}(h]h ]h"]h$]h&]uh1jj hjZ ubh or similar, you should }(hjZ hhhNhNubh)}(h**not**h]hnot}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjZ ubh call it }(hjZ hhhNhNubjk )}(h``cntusr()``h]hcntusr()}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jj hjZ ubh.}(hjZ 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 hhhNhNubjk )}(h``i``h]hi}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jj hj ubh
.
Calling it }(hj hhhNhNubjk )}(h``loop_counter``h]hloop_counter}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jj hj ubhR is non-productive, if there is no chance of it
being mis-understood. Similarly, }(hj hhhNhNubjk )}(h``tmp``h]htmp}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jj 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&]uh1j9 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:}(hj\ hhhNhNubah}(h]h ]h"]h$]h&]uh1j) hhhM_hjX ubj: )}(hhh]h)}(h-'denylist / allowlist'
'blocklist / passlist'h]h5‘denylist / allowlist’
‘blocklist / passlist’}(hjm hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM^hjj ubah}(h]h ]h"]h$]h&]uh1j9 hjX 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.}(hj 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 hhhNhNubjk )}(h ``vps_t``h]hvps_t}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jj 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 hhhNhNubjk )}(h``a``h]ha}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jj 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 }(hj2 hhhNhNubjk )}(h``help readability``h]hhelp readability}(hj: hhhNhNubah}(h]h ]h"]h$]h&]uh1jj hj2 ubh#. Not so. They are
useful only for:}(hj2 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 }(hjc hhhNhNubh)}(h**hide**h]hhide}(hjk hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjc ubh
what the object is).}(hjc hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhM~hj_ ubh)}(hdExample: ``pte_t`` etc. opaque objects that you can only access using
the proper accessor functions.h](h Example: }(hj hhhNhNubjk )}(h ``pte_t``h]hpte_t}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jj hj ubhR etc. opaque objects that you can only access using
the proper accessor functions.}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhj_ 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 hhhNhNubjk )}(h``accessor functions``h]haccessor functions}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jj 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 hj_ ubeh}(h]h ]h"]h$]h&]uh1j] hjZ ubj^ )}(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 hhhNhNubjk )}(h``int``h]hint}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jj hj ubh or }(hj hhhNhNubjk )}(h``long``h]hlong}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jj 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 }(hjA hhhNhNubh)}(h
**reason**h]hreason}(hjI hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjA ubh for this. If something is
}(hjA hhhNhNubjk )}(h``unsigned long``h]h
unsigned long}(hj[ hhhNhNubah}(h]h ]h"]h$]h&]uh1jj hjA ubh , then there’s no reason to do}(hjA hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhj= ubjS )}(h typedef unsigned long myflags_t;h]h)}(hju h]h typedef unsigned long myflags_t;}(hjw hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjs ubah}(h]h ]h"]h$]h&]uh1jR 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 hhhNhNubjk )}(h``unsigned int``h]hunsigned int}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jj hj ubh) and under other configurations might be
}(hj hhhNhNubjk )}(h``unsigned long``h]h
unsigned long}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jj 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&]uh1j] hjZ ubj^ )}(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&]uh1j] hjZ ubj^ )}(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
hhhNhNubjk )}(h``uint32_t``h]huint32_t}(hj
hhhNhNubah}(h]h ]h"]h$]h&]uh1jj 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$
hhhNhNubjk )}(h``u8/u16/u32/u64``h]hu8/u16/u32/u64}(hj,
hhhNhNubah}(h]h ]h"]h$]h&]uh1jj 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.}(hjD
hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj ubeh}(h]h ]h"]h$]h&]uh1j] hjZ ubj^ )}(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.}(hj\
hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjX
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 }(hjj
hhhNhNubjk )}(h``u32``h]hu32}(hjr
hhhNhNubah}(h]h ]h"]h$]h&]uh1jj hjj
ubhd form above. Thus, we
use __u32 and similar types in all structures which are shared
with userspace.}(hjj
hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjX
ubeh}(h]h ]h"]h$]h&]uh1j] hjZ ubeh}(h]h ]h"]h$]h&]enumtype
loweralphaprefix(suffix)uh1jX hjT ubah}(h]h ]h"]h$]h&]uh1jR 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);}hjA 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}(hjS hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjP 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.}(hja hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjP 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 }(hjo hhhNhNubjk )}(h
``extern``h]hextern}(hjw hhhNhNubah}(h]h ]h"]h$]h&]uh1jj hjo ubh^ keyword with function declarations as this makes
lines longer and isn’t strictly necessary.}(hjo hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjP 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&]uh1hhhhMhjP 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 hhhMhjP hhubh)}(h