1 This file has moved to process/coding-style.rs !! 1
>> 2 Linux kernel coding style
>> 3
>> 4 This is a short document describing the preferred coding style for the
>> 5 linux kernel. Coding style is very personal, and I won't _force_ my
>> 6 views on anybody, but this is what goes for anything that I have to be
>> 7 able to maintain, and I'd prefer it for most other things too. Please
>> 8 at least consider the points made here.
>> 9
>> 10 First off, I'd suggest printing out a copy of the GNU coding standards,
>> 11 and NOT read it. Burn them, it's a great symbolic gesture.
>> 12
>> 13 Anyway, here goes:
>> 14
>> 15
>> 16 Chapter 1: Indentation
>> 17
>> 18 Tabs are 8 characters, and thus indentations are also 8 characters.
>> 19 There are heretic movements that try to make indentations 4 (or even 2!)
>> 20 characters deep, and that is akin to trying to define the value of PI to
>> 21 be 3.
>> 22
>> 23 Rationale: The whole idea behind indentation is to clearly define where
>> 24 a block of control starts and ends. Especially when you've been looking
>> 25 at your screen for 20 straight hours, you'll find it a lot easier to see
>> 26 how the indentation works if you have large indentations.
>> 27
>> 28 Now, some people will claim that having 8-character indentations makes
>> 29 the code move too far to the right, and makes it hard to read on a
>> 30 80-character terminal screen. The answer to that is that if you need
>> 31 more than 3 levels of indentation, you're screwed anyway, and should fix
>> 32 your program.
>> 33
>> 34 In short, 8-char indents make things easier to read, and have the added
>> 35 benefit of warning you when you're nesting your functions too deep.
>> 36 Heed that warning.
>> 37
>> 38
>> 39 Chapter 2: Placing Braces
>> 40
>> 41 The other issue that always comes up in C styling is the placement of
>> 42 braces. Unlike the indent size, there are few technical reasons to
>> 43 choose one placement strategy over the other, but the preferred way, as
>> 44 shown to us by the prophets Kernighan and Ritchie, is to put the opening
>> 45 brace last on the line, and put the closing brace first, thusly:
>> 46
>> 47 if (x is true) {
>> 48 we do y
>> 49 }
>> 50
>> 51 However, there is one special case, namely functions: they have the
>> 52 opening brace at the beginning of the next line, thus:
>> 53
>> 54 int function(int x)
>> 55 {
>> 56 body of function
>> 57 }
>> 58
>> 59 Heretic people all over the world have claimed that this inconsistency
>> 60 is ... well ... inconsistent, but all right-thinking people know that
>> 61 (a) K&R are _right_ and (b) K&R are right. Besides, functions are
>> 62 special anyway (you can't nest them in C).
>> 63
>> 64 Note that the closing brace is empty on a line of its own, _except_ in
>> 65 the cases where it is followed by a continuation of the same statement,
>> 66 ie a "while" in a do-statement or an "else" in an if-statement, like
>> 67 this:
>> 68
>> 69 do {
>> 70 body of do-loop
>> 71 } while (condition);
>> 72
>> 73 and
>> 74
>> 75 if (x == y) {
>> 76 ..
>> 77 } else if (x > y) {
>> 78 ...
>> 79 } else {
>> 80 ....
>> 81 }
>> 82
>> 83 Rationale: K&R.
>> 84
>> 85 Also, note that this brace-placement also minimizes the number of empty
>> 86 (or almost empty) lines, without any loss of readability. Thus, as the
>> 87 supply of new-lines on your screen is not a renewable resource (think
>> 88 25-line terminal screens here), you have more empty lines to put
>> 89 comments on.
>> 90
>> 91
>> 92 Chapter 3: Naming
>> 93
>> 94 C is a Spartan language, and so should your naming be. Unlike Modula-2
>> 95 and Pascal programmers, C programmers do not use cute names like
>> 96 ThisVariableIsATemporaryCounter. A C programmer would call that
>> 97 variable "tmp", which is much easier to write, and not the least more
>> 98 difficult to understand.
>> 99
>> 100 HOWEVER, while mixed-case names are frowned upon, descriptive names for
>> 101 global variables are a must. To call a global function "foo" is a
>> 102 shooting offense.
>> 103
>> 104 GLOBAL variables (to be used only if you _really_ need them) need to
>> 105 have descriptive names, as do global functions. If you have a function
>> 106 that counts the number of active users, you should call that
>> 107 "count_active_users()" or similar, you should _not_ call it "cntusr()".
>> 108
>> 109 Encoding the type of a function into the name (so-called Hungarian
>> 110 notation) is brain damaged - the compiler knows the types anyway and can
>> 111 check those, and it only confuses the programmer. No wonder MicroSoft
>> 112 makes buggy programs.
>> 113
>> 114 LOCAL variable names should be short, and to the point. If you have
>> 115 some random integer loop counter, it should probably be called "i".
>> 116 Calling it "loop_counter" is non-productive, if there is no chance of it
>> 117 being mis-understood. Similarly, "tmp" can be just about any type of
>> 118 variable that is used to hold a temporary value.
>> 119
>> 120 If you are afraid to mix up your local variable names, you have another
>> 121 problem, which is called the function-growth-hormone-imbalance syndrome.
>> 122 See next chapter.
>> 123
>> 124
>> 125 Chapter 4: Functions
>> 126
>> 127 Functions should be short and sweet, and do just one thing. They should
>> 128 fit on one or two screenfuls of text (the ISO/ANSI screen size is 80x24,
>> 129 as we all know), and do one thing and do that well.
>> 130
>> 131 The maximum length of a function is inversely proportional to the
>> 132 complexity and indentation level of that function. So, if you have a
>> 133 conceptually simple function that is just one long (but simple)
>> 134 case-statement, where you have to do lots of small things for a lot of
>> 135 different cases, it's OK to have a longer function.
>> 136
>> 137 However, if you have a complex function, and you suspect that a
>> 138 less-than-gifted first-year high-school student might not even
>> 139 understand what the function is all about, you should adhere to the
>> 140 maximum limits all the more closely. Use helper functions with
>> 141 descriptive names (you can ask the compiler to in-line them if you think
>> 142 it's performance-critical, and it will probably do a better job of it
>> 143 than you would have done).
>> 144
>> 145 Another measure of the function is the number of local variables. They
>> 146 shouldn't exceed 5-10, or you're doing something wrong. Re-think the
>> 147 function, and split it into smaller pieces. A human brain can
>> 148 generally easily keep track of about 7 different things, anything more
>> 149 and it gets confused. You know you're brilliant, but maybe you'd like
>> 150 to understand what you did 2 weeks from now.
>> 151
>> 152
>> 153 Chapter 5: Commenting
>> 154
>> 155 Comments are good, but there is also a danger of over-commenting. NEVER
>> 156 try to explain HOW your code works in a comment: it's much better to
>> 157 write the code so that the _working_ is obvious, and it's a waste of
>> 158 time to explain badly written code.
>> 159
>> 160 Generally, you want your comments to tell WHAT your code does, not HOW.
>> 161 Also, try to avoid putting comments inside a function body: if the
>> 162 function is so complex that you need to separately comment parts of it,
>> 163 you should probably go back to chapter 4 for a while. You can make
>> 164 small comments to note or warn about something particularly clever (or
>> 165 ugly), but try to avoid excess. Instead, put the comments at the head
>> 166 of the function, telling people what it does, and possibly WHY it does
>> 167 it.
>> 168
>> 169
>> 170 Chapter 6: You've made a mess of it
>> 171
>> 172 That's OK, we all do. You've probably been told by your long-time Unix
>> 173 user helper that "GNU emacs" automatically formats the C sources for
>> 174 you, and you've noticed that yes, it does do that, but the defaults it
>> 175 uses are less than desirable (in fact, they are worse than random
>> 176 typing - an infinite number of monkeys typing into GNU emacs would never
>> 177 make a good program).
>> 178
>> 179 So, you can either get rid of GNU emacs, or change it to use saner
>> 180 values. To do the latter, you can stick the following in your .emacs file:
>> 181
>> 182 (defun linux-c-mode ()
>> 183 "C mode with adjusted defaults for use with the Linux kernel."
>> 184 (interactive)
>> 185 (c-mode)
>> 186 (c-set-style "K&R")
>> 187 (setq c-basic-offset 8))
>> 188
>> 189 This will define the M-x linux-c-mode command. When hacking on a
>> 190 module, if you put the string -*- linux-c -*- somewhere on the first
>> 191 two lines, this mode will be automatically invoked. Also, you may want
>> 192 to add
>> 193
>> 194 (setq auto-mode-alist (cons '("/usr/src/linux.*/.*\\.[ch]$" . linux-c-mode)
>> 195 auto-mode-alist))
>> 196
>> 197 to your .emacs file if you want to have linux-c-mode switched on
>> 198 automagically when you edit source files under /usr/src/linux.
>> 199
>> 200 But even if you fail in getting emacs to do sane formatting, not
>> 201 everything is lost: use "indent".
>> 202
>> 203 Now, again, GNU indent has the same brain-dead settings that GNU emacs
>> 204 has, which is why you need to give it a few command line options.
>> 205 However, that's not too bad, because even the makers of GNU indent
>> 206 recognize the authority of K&R (the GNU people aren't evil, they are
>> 207 just severely misguided in this matter), so you just give indent the
>> 208 options "-kr -i8" (stands for "K&R, 8 character indents").
>> 209
>> 210 "indent" has a lot of options, and especially when it comes to comment
>> 211 re-formatting you may want to take a look at the manual page. But
>> 212 remember: "indent" is not a fix for bad programming.
>> 213
>> 214
>> 215 Chapter 7: Configuration-files
>> 216
>> 217 For configuration options (arch/xxx/config.in, and all the Config.in files),
>> 218 somewhat different indentation is used.
>> 219
>> 220 An indention level of 3 is used in the code, while the text in the config-
>> 221 options should have an indention-level of 2 to indicate dependencies. The
>> 222 latter only applies to bool/tristate options. For other options, just use
>> 223 common sense. An example:
>> 224
>> 225 if [ "$CONFIG_EXPERIMENTAL" = "y" ]; then
>> 226 tristate 'Apply nitroglycerine inside the keyboard (DANGEROUS)' CONFIG_BOOM
>> 227 if [ "$CONFIG_BOOM" != "n" ]; then
>> 228 bool ' Output nice messages when you explode' CONFIG_CHEER
>> 229 fi
>> 230 fi
>> 231
>> 232 Generally, CONFIG_EXPERIMENTAL should surround all options not considered
>> 233 stable. All options that are known to trash data (experimental write-
>> 234 support for file-systems, for instance) should be denoted (DANGEROUS), other
>> 235 experimental options should be denoted (EXPERIMENTAL).
>> 236
>> 237
>> 238 Chapter 8: Data structures
>> 239
>> 240 Data structures that have visibility outside the single-threaded
>> 241 environment they are created and destroyed in should always have
>> 242 reference counts. In the kernel, garbage collection doesn't exist (and
>> 243 outside the kernel garbage collection is slow and inefficient), which
>> 244 means that you absolutely _have_ to reference count all your uses.
>> 245
>> 246 Reference counting means that you can avoid locking, and allows multiple
>> 247 users to have access to the data structure in parallel - and not having
>> 248 to worry about the structure suddenly going away from under them just
>> 249 because they slept or did something else for a while.
>> 250
>> 251 Note that locking is _not_ a replacement for reference counting.
>> 252 Locking is used to keep data structures coherent, while reference
>> 253 counting is a memory management technique. Usually both are needed, and
>> 254 they are not to be confused with each other.
>> 255
>> 256 Many data structures can indeed have two levels of reference counting,
>> 257 when there are users of different "classes". The subclass count counts
>> 258 the number of subclass users, and decrements the global count just once
>> 259 when the subclass count goes to zero.
>> 260
>> 261 Examples of this kind of "multi-level-reference-counting" can be found in
>> 262 memory management ("struct mm_struct": mm_users and mm_count), and in
>> 263 filesystem code ("struct super_block": s_count and s_active).
>> 264
>> 265 Remember: if another thread can find your data structure, and you don't
>> 266 have a reference count on it, you almost certainly have a bug.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.