Skip to content

Commit

Permalink
doc: contribute: split style guidelines into own document
Browse files Browse the repository at this point in the history 
Move style guidelines into own section and put it along side other
guidelines.

Signed-off-by: Anas Nashif <anas.nashif@intel.com>
  • Loading branch information
@nashif @kartben
nashif authored and kartben committed Jan 22, 2025
1 parent 09a0beb commit 22b1e70
Show file tree
Hide file tree
Showing 3 changed files with 154 additions and 142 deletions.
140 changes: 0 additions & 140 deletions doc/contribute/guidelines.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -506,146 +506,6 @@ reference manuals, etc.
Link: https://github.com/zephyrproject-rtos/zephyr/issues/<issue number>
.. _coding_style:

Coding Style
============

.. note::
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.

.. note::
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).

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

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

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``

Use these coding guidelines to ensure that your development complies with the
project's style and naming conventions.

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 more complete alternative to this is using :ref:`check_compliance_py` script.

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`_ 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 and the
formatting generated by code formatting tools, the `Coding Style`_ guidelines
take precedence. If there is ambiguity between formatting tools and the
guidelines, maintainers may decide which style should be adopted.

.. _Continuous Integration:

Continuous Integration (CI)
Expand Down
6 changes: 4 additions & 2 deletions doc/contribute/index.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,7 @@ General Guidelines
contributor_expectations.rst
reviewer_expectations.rst
coding_guidelines/index.rst
style_guidelines.rst
proposals_and_rfcs.rst
modifying_contributions.rst

Expand All @@ -41,8 +42,9 @@ General Guidelines
Code contributions are expected to follow a set of coding guidelines to ensure consistency and
readability across the code base.

This page describes these guidelines and introduces important considerations regarding the use of
:ref:`inclusive language <coding_guideline_inclusive_language>`.
:ref:`coding_style`
Code contributions are expected to follow a set of style guidelines to ensure consistency and
readability across the code base.

:ref:`rfcs`
Learn when and how to submit RFCs (Request for Comments) for new features and changes to the
Expand Down
150 changes: 150 additions & 0 deletions doc/contribute/style_guidelines.rst
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,150 @@
.. _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

0 comments on commit 22b1e70

Please sign in to comment.