Documentation/process/4.Coding.rst

Source file repositories/reference/linux-study-clean/Documentation/process/4.Coding.rst

File Facts

System
Linux kernel
Corpus path
Documentation/process/4.Coding.rst
Extension
.rst
Size
21895 bytes
Lines
426
Domain
Support Tooling And Documentation
Bucket
Documentation
Inferred role
Support Tooling And Documentation: documentation
Status
atlas-only

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

Dependency Surface

Detected Declarations

Annotated Snippet

.. _development_coding:

Getting the code right
======================

While there is much to be said for a solid and community-oriented design
process, the proof of any kernel development project is in the resulting
code.  It is the code which will be examined by other developers and merged
(or not) into the mainline tree.  So it is the quality of this code which
will determine the ultimate success of the project.

This section will examine the coding process.  We'll start with a look at a
number of ways in which kernel developers can go wrong.  Then the focus
will shift toward doing things right and the tools which can help in that
quest.


Pitfalls
---------

Coding style
************

The kernel has long had a standard coding style, described in
:ref:`Documentation/process/coding-style.rst <codingstyle>`.  For much of
that time, the policies described in that file were taken as being, at most,
advisory.  As a result, there is a substantial amount of code in the kernel
which does not meet the coding style guidelines.  The presence of that code
leads to two independent hazards for kernel developers.

The first of these is to believe that the kernel coding standards do not
matter and are not enforced.  The truth of the matter is that adding new
code to the kernel is very difficult if that code is not coded according to
the standard; many developers will request that the code be reformatted
before they will even review it.  A code base as large as the kernel
requires some uniformity of code to make it possible for developers to
quickly understand any part of it.  So there is no longer room for
strangely-formatted code.

Occasionally, the kernel's coding style will run into conflict with an
employer's mandated style.  In such cases, the kernel's style will have to
win before the code can be merged.  Putting code into the kernel means
giving up a degree of control in a number of ways - including control over
how the code is formatted.

The other trap is to assume that code which is already in the kernel is
urgently in need of coding style fixes.  Developers may start to generate
reformatting patches as a way of gaining familiarity with the process, or
as a way of getting their name into the kernel changelogs - or both.  But
pure coding style fixes are seen as noise by the development community;
they tend to get a chilly reception.  So this type of patch is best
avoided.  It is natural to fix the style of a piece of code while working
on it for other reasons, but coding style changes should not be made for
their own sake.

The coding style document also should not be read as an absolute law which
can never be transgressed.  If there is a good reason to go against the
style (a line which becomes far less readable if split to fit within the
80-column limit, for example), just do it.

Note that you can also use the ``clang-format`` tool to help you with
these rules, to quickly re-format parts of your code automatically,
and to review full files in order to spot coding style mistakes,
typos and possible improvements. It is also handy for sorting ``#includes``,
for aligning variables/macros, for reflowing text and other similar tasks.
See the file :ref:`Documentation/dev-tools/clang-format.rst <clangformat>`
for more details.

Some basic editor settings, such as indentation and line endings, will be
set automatically if you are using an editor that is compatible with

Annotation

Implementation Notes