doc: contribute: split style guidelines into own document
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
Benjamin Cabé
parent
09a0bebdd1
commit
22b1e70b08
3 changed files with 154 additions and 142 deletions
|
|
@ -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)
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
@ -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
|
||||
|
|
|
|||
150
doc/contribute/style_guidelines.rst
Normal file
150
doc/contribute/style_guidelines.rst
Normal 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
|
||||
Loading…
Reference in a new issue