From b1043de5d31109c86ec151cc4b08ab47d76d35e3 Mon Sep 17 00:00:00 2001 From: Anas Nashif Date: Wed, 22 Jan 2025 07:58:28 -0500 Subject: [PATCH] doc: contribute: split style guidelines Split style guidelines into multiple pages to allow expansion and adding more details and levels. Signed-off-by: Anas Nashif --- doc/contribute/index.rst | 2 +- doc/contribute/style/cmake.rst | 16 +-- doc/contribute/style/code.rst | 38 +++++++ doc/contribute/style/devicetree.rst | 13 +++ doc/contribute/style/index.rst | 87 ++++++++++++++++ doc/contribute/style/kconfig.rst | 14 +++ doc/contribute/style_guidelines.rst | 155 ---------------------------- 7 files changed, 161 insertions(+), 164 deletions(-) create mode 100644 doc/contribute/style/code.rst create mode 100644 doc/contribute/style/devicetree.rst create mode 100644 doc/contribute/style/index.rst create mode 100644 doc/contribute/style/kconfig.rst delete mode 100644 doc/contribute/style_guidelines.rst diff --git a/doc/contribute/index.rst b/doc/contribute/index.rst index 8b364aa1b4b..a6c2998a818 100644 --- a/doc/contribute/index.rst +++ b/doc/contribute/index.rst @@ -18,7 +18,7 @@ General Guidelines contributor_expectations.rst reviewer_expectations.rst coding_guidelines/index.rst - style_guidelines.rst + style/index.rst proposals_and_rfcs.rst modifying_contributions.rst diff --git a/doc/contribute/style/cmake.rst b/doc/contribute/style/cmake.rst index 44cdb42ed0f..0fff4273416 100644 --- a/doc/contribute/style/cmake.rst +++ b/doc/contribute/style/cmake.rst @@ -3,10 +3,10 @@ .. _cmake-style: CMake Style Guidelines -====================== +###################### General Formatting ------------------- +****************** - **Indentation**: Use **2 spaces** for indentation. Avoid tabs to ensure consistency across different environments. @@ -30,7 +30,7 @@ General Formatting endif() Commands and Syntax -------------------- +******************* - **Lowercase Commands**: Always use **lowercase** CMake commands (e.g., ``add_executable``, ``find_package``). This improves readability and @@ -59,7 +59,7 @@ Commands and Syntax target_sources(my_target PRIVATE src/file1.cpp src/file2.cpp) Variable Naming ---------------- +*************** - **Use Uppercase for Cache Variables or variables shared across CMake files**: When defining cache variables using ``option`` or ``set(... CACHE ...)``, use @@ -85,7 +85,7 @@ Variable Naming set(MYPROJECT_SRC_DIR "${CMAKE_SOURCE_DIR}/src") Quoting -------- +******* - **Quote Strings and Variables**: Always quote string literals and variables to prevent unintended behavior, especially when dealing with paths or @@ -107,7 +107,7 @@ Quoting option(BUILD_SHARED_LIBS "Build shared libraries" OFF) Avoid Hardcoding Paths ----------------------- +********************** - Use CMake variables (``CMAKE_SOURCE_DIR``, ``CMAKE_BINARY_DIR``, ``CMAKE_CURRENT_SOURCE_DIR``) instead of hardcoding paths. @@ -117,7 +117,7 @@ Avoid Hardcoding Paths set(output_dir "${CMAKE_BINARY_DIR}/bin") Conditional Logic ------------------ +***************** - Use ``if``, ``elseif``, and ``else`` with proper indentation, and close with ``endif()``. @@ -129,7 +129,7 @@ Conditional Logic endif() Documentation -------------- +************* - Use comments to document complex logic in the CMake files. diff --git a/doc/contribute/style/code.rst b/doc/contribute/style/code.rst new file mode 100644 index 00000000000..59a363ee509 --- /dev/null +++ b/doc/contribute/style/code.rst @@ -0,0 +1,38 @@ +.. _general_code_style: + +C Code and General Style Guidelines +################################### + +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``). + +.. _Linux kernel coding style: + https://kernel.org/doc/html/latest/process/coding-style.html + +.. _snake case: + https://en.wikipedia.org/wiki/Snake_case diff --git a/doc/contribute/style/devicetree.rst b/doc/contribute/style/devicetree.rst new file mode 100644 index 00000000000..36746770754 --- /dev/null +++ b/doc/contribute/style/devicetree.rst @@ -0,0 +1,13 @@ +.. _devicetree_style: + +Devicetree Style Guidelines +########################### + + * 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. diff --git a/doc/contribute/style/index.rst b/doc/contribute/style/index.rst new file mode 100644 index 00000000000..d0ff1814d4c --- /dev/null +++ b/doc/contribute/style/index.rst @@ -0,0 +1,87 @@ +.. _coding_style: + + +Coding Style Guidelines +####################### + +.. toctree:: + :maxdepth: 1 + + code.rst + cmake.rst + devicetree.rst + kconfig.rst + + +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. diff --git a/doc/contribute/style/kconfig.rst b/doc/contribute/style/kconfig.rst new file mode 100644 index 00000000000..f73165e28d4 --- /dev/null +++ b/doc/contribute/style/kconfig.rst @@ -0,0 +1,14 @@ +.. _kconfig_style: + +Kconfig Style Guidelines +######################## + + * 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. diff --git a/doc/contribute/style_guidelines.rst b/doc/contribute/style_guidelines.rst deleted file mode 100644 index 2cd2f533423..00000000000 --- a/doc/contribute/style_guidelines.rst +++ /dev/null @@ -1,155 +0,0 @@ -.. _coding_style: - - -Coding Style Guidelines -####################### - -.. toctree:: - :maxdepth: 1 - - style/cmake.rst - -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