Documentation/process/4.Coding.rst

6 While there is much to be said for a solid and community-oriented design
8 code.  It is the code which will be examined by other developers and merged
34 the standard; many developers will request that the code be reformatted
42 win before the code can be merged.  Putting code into the kernel means
53 on it for other reasons, but coding style changes should not be made for
56 The coding style document also should not be read as an absolute law which
57 can never be transgressed.  If there is a good reason to go against the
69 Some basic editor settings, such as indentation and line endings, will be
81 But experience has shown that excessive or premature abstraction can be
82 just as harmful as premature optimization.  Abstraction should be used to
93 patches to remove unused arguments; they should, in general, not be added
97 of a driver to be used with multiple operating systems - are especially
121 should be confined to header files whenever possible.
122 Conditionally-compiled code can be confined to functions which, if the code
123 is not to be present, simply become empty.  The compiler will then quietly
130 instead.  The code which results will be the same, but inline functions are
144 slow execution dramatically.  Inline functions, as a rule, should be quite
155 a given function should actually be inlined or not.  So the liberal
156 placement of "inline" keywords may not just be excessive; it could also be
174 (now called mac80211) could be merged, a locking scheme needed to be
177 Once upon a time, Linux kernel code could be developed without thinking
182 code could be written without thinking about locking are long past.
184 Any resource (data structures, hardware registers, etc.) which could be
185 accessed concurrently by more than one thread must be protected by a lock.
186 New code should be written with this requirement in mind; retrofitting
196 One final hazard worth mentioning is this: it can be tempting to make a
200 exceptions, changes which cause regressions will be backed out if the
201 regression cannot be fixed in a timely manner.  Far better to avoid the
204 It is often argued that a regression can be justified if it causes things
221 be supported indefinitely.  This fact makes the creation of user-space
222 interfaces particularly challenging: since they cannot be changed in
223 incompatible ways, they must be done right the first time.  For this
238 tools should be used whenever possible.
253 of these options should be turned on for any kernel used for development or
257    The output generated can be verbose, but one need not worry about
267    should be used on most development kernels.
272 There are quite a few other debugging options, some of which will be
274 should not be used all of the time.  But some time spent learning the
275 available options will likely be paid back many times over in short order.
284 occasion, deadlock.  This kind of problem can be painful (for both
285 developers and users) in a deployed system; lockdep allows them to be found
287 locking should be run with lockdep enabled before being submitted for
293 are, probably, completely untested.  Untested code tends to be broken code;
294 you could be much more confident of your code if all those error-handling
299 enabled, a configurable percentage of memory allocations will be made to
300 fail; these failures can be restricted to a specific range of code.
306 Other kinds of errors can be found with the "sparse" static analysis tool.
307 With sparse, the programmer can be warned about confusion between
310 flags is expected, and so on.  Sparse must be installed separately (it can
311 be found at https://sparse.wiki.kernel.org/index.php/Main_Page if your
312 distributor does not package it); it can then be run on the code by adding
326 step.  A large set of cross compilers for x86 systems can be found at
340 will be helpful for your users.  In many cases, the addition of
346 effects on performance, and anything else that might be needed to
347 understand the patch.  Be sure that the changelog says *why* the patch is
355 be formatted and what information needs to be provided.
362 Any new configuration options must be accompanied by help text which
366 specially-formatted comments; these comments can be extracted and formatted
371 comments for the future; indeed, this can be a useful activity for
373 information on how to create kerneldoc templates can be found at
379 merging uncommented code will be harder.  That said, there is little desire
380 for verbosely-commented code.  The code should, itself, be readable, with
383 Certain things should always be commented.  Uses of memory barriers should
384 be accompanied by a line explaining why the barrier is necessary.  The
385 locking rules for data structures generally need to be explained somewhere.
387 Non-obvious dependencies between separate bits of code should be pointed
395 The binary interface provided by the kernel to user space cannot be broken
397 programming interfaces, instead, are highly fluid and can be changed when
400 needs, that may be a sign that the API needs to change.  As a kernel
403 There are, of course, some catches.  API changes can be made, but they need
404 to be well justified.  So any patch making an internal API change should be
406 necessary.  This kind of change should also be broken out into a separate
414 say, this can be a large job, so it is best to be sure that the
420 This will help you to be sure that you have found all in-tree uses of that
423 something that kernel developers need to be worried about, but we also do
425 be.