zephyr/doc/contribute/style_guidelines.rst

.. _coding_style:


Coding Style Guidelines
#######################

C Code and General Style
************************

Coding style is enforced on any new or modified code, but contributors are
not expected to correct the style on existing code that they are not
modifying.

For style aspects where the guidelines don't offer explicit guidance or
permit multiple valid ways to express something, contributors should follow
the style of existing code in the tree, with higher importance given to
"nearby" code (first look at the function, then the same file, then
subsystem, etc).

In general, follow the `Linux kernel coding style`_, with the following
exceptions and clarifications:

* Use `snake case`_ for code and variables.
* The line length is 100 columns or fewer. In the documentation, longer lines
  for URL references are an allowed exception.
* Add braces to every ``if``, ``else``, ``do``, ``while``, ``for`` and
  ``switch`` body, even for single-line code blocks.
* Use spaces instead of tabs to align comments after declarations, as needed.
* Use C89-style single line comments, ``/*  */``. The C99-style single line
  comment, ``//``, is not allowed.
* Use ``/**  */`` for doxygen comments that need to appear in the documentation.
* Avoid using binary literals (constants starting with ``0b``).
* Avoid using non-ASCII symbols in code, unless it significantly improves
  clarity, avoid emojis in any case.
* Use proper capitalization of nouns in code comments (e.g. ``UART`` and not
  ``uart``, ``CMake`` and not ``cmake``).

Beyond C code, the following coding style rules apply to other types of files:

CMake
*****

  * Indent with spaces, indentation is two spaces.
  * Don't use space between commands (e.g. ``if``) and the corresponding opening
    bracket (e.g. ``(``).

Devicetree
**********

  * Indent with tabs.
  * Follow the Devicetree specification conventions and rules.
  * Use dashes (``-``) as word separators for node and property names.
  * Use underscores (``_``) as word separators in node labels.
  * Leave a single space on each side of the equal sign (``=``) in property
    definitions.
  * Don't insert empty lines before a dedenting ``};``.
  * Insert a single empty line to separate nodes at the same hierarchy level.

Kconfig
*******

  * Line length of 100 columns or fewer.
  * Indent with tabs, except for ``help`` entry text which should be placed at
    one tab plus two extra spaces.
  * Leave a single empty line between option declarations.
  * Use Statements like ``select`` carefully, see
    :ref:`kconfig_tips_and_tricks` for more information.
  * Format comments as ``# Comment`` rather than ``#Comment``
  * Insert an empty line before/after each top-level ``if`` and ``endif``
    statement.

Style Tools
***********

Checkpatch
==========

The Linux kernel GPL-licensed tool ``checkpatch`` is used to check
coding style conformity.

.. note::
   checkpatch does not currently run on Windows.

Checkpatch is available in the scripts directory. To invoke it when committing
code, make the file *$ZEPHYR_BASE/.git/hooks/pre-commit* executable and edit
it to contain:

.. code-block:: bash

    #!/bin/sh
    set -e exec
    exec git diff --cached | ${ZEPHYR_BASE}/scripts/checkpatch.pl -

Instead of running checkpatch at each commit, you may prefer to run it only
before pushing on zephyr repo. To do this, make the file
*$ZEPHYR_BASE/.git/hooks/pre-push* executable and edit it to contain:

.. code-block:: bash

    #!/bin/sh
    remote="$1"
    url="$2"

    z40=0000000000000000000000000000000000000000

    echo "Run push hook"

    while read local_ref local_sha remote_ref remote_sha
    do
        args="$remote $url $local_ref $local_sha $remote_ref $remote_sha"
        exec ${ZEPHYR_BASE}/scripts/series-push-hook.sh $args
    done

    exit 0

If you want to override checkpatch verdict and push you branch despite reported
issues, you can add option --no-verify to the git push command.

A different way for running ``checkpatch`` is by using :ref:`check_compliance_py`
script, which does additional style and compliance related checks.

clang-format
============

The `clang-format tool <https://clang.llvm.org/docs/ClangFormat.html>`_ can
be helpful to quickly reformat large amounts of new source code to our
`Coding Style Guidelines`_ standards together with the ``.clang-format`` configuration file
provided in the repository. ``clang-format`` is well integrated into most
editors, but you can also run it manually like this:

.. code-block:: bash

   clang-format -i my_source_file.c

``clang-format`` is part of LLVM, which can be downloaded from the project
`releases page <https://github.com/llvm/llvm-project/releases>`_. Note that if
you are a Linux user, ``clang-format`` will likely be available as a package in
your distribution repositories.

When there are differences between the `Coding Style Guidelines`_ guidelines and the
formatting generated by code formatting tools, the `Coding Style Guidelines`_ guidelines
take precedence. If there is ambiguity between formatting tools and the
guidelines, maintainers may decide which style should be adopted.


.. _Linux kernel coding style:
   https://kernel.org/doc/html/latest/process/coding-style.html

.. _snake case:
   https://en.wikipedia.org/wiki/Snake_case