Documentation/process/4.Coding.rst

6 While there is much to be said for a solid and community-oriented design
19 ---------
25 :ref:`Documentation/process/coding-style.rst <codingstyle>`.  For much of
38 strangely-formatted code.
43 giving up a degree of control in a number of ways - including control over
49 as a way of getting their name into the kernel changelogs - or both.  But
59 80-column limit, for example), just do it.
61 Note that you can also use the ``clang-format`` tool to help you with
62 these rules, to quickly re-format parts of your code automatically,
66 See the file :ref:`Documentation/dev-tools/clang-format.rst <clangformat>`
90 never noticed - because it has never been used.  Or, when the need for
96 Abstraction layers which hide access to hardware - often to allow the bulk
97 of a driver to be used with multiple operating systems - are especially
103 make sense to pull out some of that code into a separate library or to
122 Conditionally-compiled code can be confined to functions which, if the code
124 optimize out the call to the empty function.  The result is far cleaner
130 instead.  The code which results will be the same, but inline functions are
135 Inline functions
138 Inline functions present a hazard of their own, though.  Programmers can
140 call and fill a source file with inline functions.  Those functions,
144 slow execution dramatically.  Inline functions, as a rule, should be quite
146 that high; the creation of large numbers of inline functions is a classic
179 however, this document is being written on a dual-core laptop.  Even on
180 single-processor systems, work being done to improve responsiveness will
200 exceptions, changes which cause regressions will be backed out if the
220 user-space ABI.  Once an interface has been exported to user space, it must
221 be supported indefinitely.  This fact makes the creation of user-space
225 user-space interfaces is always required.
229 -------------------
231 For now, at least, the writing of error-free code remains an ideal that few
249 kernel with "make KCFLAGS=-W" to get the full set.
256  - FRAME_WARN to get warnings for stack frames larger than a given amount.
260  - DEBUG_OBJECTS will add code to track the lifetime of various objects
261    created by the kernel and warn when things are done out of order.  If
266  - DEBUG_SLAB can find a variety of memory allocation and use errors; it
269  - DEBUG_SPINLOCK, DEBUG_ATOMIC_SLEEP, and DEBUG_MUTEXES will find a
286 in an automated manner ahead of time.  Code with any sort of non-trivial
294 you could be much more confident of your code if all those error-handling
303 Documentation/fault-injection/fault-injection.rst for more information on
308 user-space and kernel-space addresses, mixture of big-endian and
309 small-endian quantities, the passing of integer values where a set of bit
320 :ref:`Documentation/dev-tools/coccinelle.rst <devtools_coccinelle>`
335 -------------
351 Any code which adds a new user-space interface - including new sysfs or
352 /proc files - should include documentation of that interface which enables
353 user-space developers to know what they are working with.  See
357 The file :ref:`Documentation/admin-guide/kernel-parameters.rst
358 <kernelparameters>` describes all of the kernel's boot-time parameters.
366 specially-formatted comments; these comments can be extracted and formatted
367 in a number of ways by the "kernel-doc" script.  If you are working within
369 them, as appropriate, for externally-available functions.  Even in areas
374 :ref:`Documentation/doc-guide/ <doc_guide>`.
380 for verbosely-commented code.  The code should, itself, be readable, with
387 Non-obvious dependencies between separate bits of code should be pointed
388 out.  Anything which might tempt a code janitor to make an incorrect
393 --------------------
406 necessary.  This kind of change should also be broken out into a separate
411 which is broken by the change.  For a widely-used function, this duty can
412 lead to literally hundreds or thousands of changes - many of which are
416 wide-ranging API changes.
420 This will help you to be sure that you have found all in-tree uses of that
421 interface.  It will also alert developers of out-of-tree code that there is
422 a change that they need to respond to.  Supporting out-of-tree code is not
424 not have to make life harder for out-of-tree developers than it needs to