Documentation/process/4.Coding.rst

3 Getting the code right
6 While there is much to be said for a solid and community-oriented design
14 will shift toward doing things right and the tools which can help in that
19 ---------
25 :ref:`Documentation/process/coding-style.rst <codingstyle>`.  For much of
26 that time, the policies described in that file were taken as being, at most,
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
122 Conditionally-compiled code can be confined to functions which, if the code
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
189 enough to pick the right tool for the job.  Code which shows a lack of
199 regressions have become most unwelcome in the mainline kernel.  With few
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
223 incompatible ways, they must be done right the first time.  For this
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.
252 features; most of these are found in the "kernel hacking" submenu.  Several
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
266  - DEBUG_SLAB can find a variety of memory allocation and use errors; it
267    should be used on most development kernels.
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>`.
377 note that, often, comments are most notable by their absence.  Once again,
380 for verbosely-commented code.  The code should, itself, be readable, with
387 Non-obvious dependencies between separate bits of code should be pointed
393 --------------------
396 except under the most severe circumstances.  The kernel's internal
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