adafruit-mirror/zephyr
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 9

doc: contribute: split style guidelines into own document

Browse source 
Move style guidelines into own section and put it along side other
guidelines.

Signed-off-by: Anas Nashif <anas.nashif@intel.com>
This commit is contained in:
Anas Nashif 2025-01-20 08:33:28 -05:00 committed by Benjamin Cabé
parent 09a0bebdd1
commit 22b1e70b08
3 changed files with 154 additions and 142 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

140
doc/contribute/guidelines.rst
View file

@ -506,146 +506,6 @@ reference manuals, etc.
Link: https://github.com/zephyrproject-rtos/zephyr/issues/<issue number> 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:
Continuous Integration (CI) Continuous Integration (CI)

6
doc/contribute/index.rst
View file

@ -18,6 +18,7 @@ General Guidelines
contributor_expectations.rst contributor_expectations.rst
reviewer_expectations.rst reviewer_expectations.rst
coding_guidelines/index.rst coding_guidelines/index.rst
style_guidelines.rst
proposals_and_rfcs.rst proposals_and_rfcs.rst
modifying_contributions.rst modifying_contributions.rst
@ -41,8 +42,9 @@ General Guidelines
Code contributions are expected to follow a set of coding guidelines to ensure consistency and Code contributions are expected to follow a set of coding guidelines to ensure consistency and
readability across the code base. readability across the code base.
This page describes these guidelines and introduces important considerations regarding the use of :ref:`coding_style`
:ref:`inclusive language <coding_guideline_inclusive_language>`. Code contributions are expected to follow a set of style guidelines to ensure consistency and
readability across the code base.
:ref:`rfcs` :ref:`rfcs`
Learn when and how to submit RFCs (Request for Comments) for new features and changes to the Learn when and how to submit RFCs (Request for Comments) for new features and changes to the

150
doc/contribute/style_guidelines.rst Normal file
View file

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