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/process/clang-format.rst <clangformat>`
86 never noticed - because it has never been used.  Or, when the need for
92 Abstraction layers which hide access to hardware - often to allow the bulk
93 of a driver to be used with multiple operating systems - are especially
118 Conditionally-compiled code can be confined to functions which, if the code
175 however, this document is being written on a dual-core laptop.  Even on
176 single-processor systems, work being done to improve responsiveness will
185 enough to pick the right tool for the job.  Code which shows a lack of
195 regressions have become most unwelcome in the mainline kernel.  With few
216 user-space ABI.  Once an interface has been exported to user space, it must
217 be supported indefinitely.  This fact makes the creation of user-space
219 incompatible ways, they must be done right the first time.  For this
221 user-space interfaces is always required.
225 -------------------
227 For now, at least, the writing of error-free code remains an ideal that few
245 kernel with "make EXTRA_CFLAGS=-W" to get the full set.
248 features; most of these are found in the "kernel hacking" submenu.  Several
252  - ENABLE_MUST_CHECK and FRAME_WARN to get an
258  - DEBUG_OBJECTS will add code to track the lifetime of various objects
264  - DEBUG_SLAB can find a variety of memory allocation and use errors; it
265    should be used on most development kernels.
267  - DEBUG_SPINLOCK, DEBUG_ATOMIC_SLEEP, and DEBUG_MUTEXES will find a
284 in an automated manner ahead of time.  Code with any sort of non-trivial
292 you could be much more confident of your code if all those error-handling
301 Documentation/fault-injection/fault-injection.rst for more information on
306 user-space and kernel-space addresses, mixture of big-endian and
307 small-endian quantities, the passing of integer values where a set of bit
318 :ref:`Documentation/dev-tools/coccinelle.rst <devtools_coccinelle>`
333 -------------
349 Any code which adds a new user-space interface - including new sysfs or
350 /proc files - should include documentation of that interface which enables
351 user-space developers to know what they are working with.  See
355 The file :ref:`Documentation/admin-guide/kernel-parameters.rst
356 <kernelparameters>` describes all of the kernel's boot-time parameters.
364 specially-formatted comments; these comments can be extracted and formatted
365 in a number of ways by the "kernel-doc" script.  If you are working within
367 them, as appropriate, for externally-available functions.  Even in areas
372 :ref:`Documentation/doc-guide/ <doc_guide>`.
375 note that, often, comments are most notable by their absence.  Once again,
378 for verbosely-commented code.  The code should, itself, be readable, with
385 Non-obvious dependencies between separate bits of code should be pointed
391 --------------------
394 except under the most severe circumstances.  The kernel's internal
409 which is broken by the change.  For a widely-used function, this duty can
410 lead to literally hundreds or thousands of changes - many of which are
414 wide-ranging API changes.
418 This will help you to be sure that you have found all in-tree uses of that
419 interface.  It will also alert developers of out-of-tree code that there is
420 a change that they need to respond to.  Supporting out-of-tree code is not
422 not have to make life harder for out-of-tree developers than it needs to