diff --git a/doc/contribute/guidelines.rst b/doc/contribute/guidelines.rst index a2c4fe45d875..2dd9566a185a 100644 --- a/doc/contribute/guidelines.rst +++ b/doc/contribute/guidelines.rst @@ -506,146 +506,6 @@ reference manuals, etc. Link: https://github.com/zephyrproject-rtos/zephyr/issues/ -.. _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 `_ 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 `_. 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) diff --git a/doc/contribute/index.rst b/doc/contribute/index.rst index 77ecfa68bebf..8b364aa1b4b0 100644 --- a/doc/contribute/index.rst +++ b/doc/contribute/index.rst @@ -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 `. +: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 diff --git a/doc/contribute/style_guidelines.rst b/doc/contribute/style_guidelines.rst new file mode 100644 index 000000000000..0a282afee22d --- /dev/null +++ b/doc/contribute/style_guidelines.rst @@ -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 `_ 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 `_. 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