From 1977b8a7cd6a6867d1394bea62989a42eb1882f7 Mon Sep 17 00:00:00 2001 From: renpeiying Date: Thu, 25 Jun 2026 17:39:21 +0800 Subject: [PATCH] docs: Update contribution docs --- docs/en/contribute/index.rst | 2 +- docs/en/contribute/style-guide.rst | 7 +- docs/zh_CN/contribute/index.rst | 30 +++---- docs/zh_CN/contribute/style-guide.rst | 111 +++++++++++++------------- 4 files changed, 76 insertions(+), 74 deletions(-) diff --git a/docs/en/contribute/index.rst b/docs/en/contribute/index.rst index af23bd747cc..00aa6be55c1 100644 --- a/docs/en/contribute/index.rst +++ b/docs/en/contribute/index.rst @@ -17,7 +17,7 @@ Before sending us a Pull Request, please consider this list of points: * Is the contribution entirely your own work, or already licensed under an Apache License 2.0 compatible Open Source License? If not then we unfortunately cannot accept it. Please check the :doc:`Copyright Header Guide ` for additional information. -* Does any new code conform to the ESP-IDF :doc:`Style Guide `? +* Does any new code conform to the :doc:`Espressif IoT Development Framework Style Guide `? * If your contribution adds or changes Python tooling, does it follow the :ref:`Python Code Style ` and reuse shared helpers from ``esp-pylib`` where applicable? diff --git a/docs/en/contribute/style-guide.rst b/docs/en/contribute/style-guide.rst index f5fb0b56887..111cf00617b 100644 --- a/docs/en/contribute/style-guide.rst +++ b/docs/en/contribute/style-guide.rst @@ -12,7 +12,7 @@ Style guide is a set of rules which are aimed to help create readable, maintaina We try to keep rules simple enough, which means that they can not cover all potential cases. In some cases one has to bend these simple rules to achieve readability, maintainability, or robustness. -When doing modifications to third-party code used in ESP-IDF, follow the way that particular project is written. That will help propose useful changes for merging into upstream project. +When modifying third-party code used in ESP-IDF, follow the coding style that particular project is written. That will help propose useful changes for merging into upstream project. C Code Formatting ----------------- @@ -202,7 +202,7 @@ If you accidentally have some commits in your branch that add LF endings, you ca Note that this line rebases on master, change the branch name at the end to rebase on another branch. -For updating a single commit, it is possible to run ``dos2unix FILENAME`` and then run ``git commit --amend``. +For updating a single commit, you can run ``dos2unix FILENAME`` first, then run ``git commit --amend``. Formatting Your Code ^^^^^^^^^^^^^^^^^^^^ @@ -497,7 +497,7 @@ Most of ESP-IDF's tooling — ``idf.py`` and its actions, the build system helpe Linting and Formatting ^^^^^^^^^^^^^^^^^^^^^^^ -Python code is linted and formatted by `Ruff `_ and type-checked by `mypy `_, configured in :project_file:`ruff.toml` and :project_file:`.mypy.ini`. You do not need to memorize the individual rules: install the :doc:`pre-commit hook ` before committing, and these tools run automatically on every commit, keeping your changes consistent with the rest of the codebase. +Python code is linted and formatted by `Ruff `_ and type-checked by `mypy `_, configured in :project_file:`ruff.toml` and :project_file:`.mypy.ini`. You do not need to memorize the individual rules: install the :doc:`pre-commit hook ` once before your first commit, and these tools run automatically on every subsequent commit, keeping your changes consistent with the rest of the codebase. Dependencies ^^^^^^^^^^^^ @@ -509,6 +509,7 @@ Reusing Shared Code (esp-pylib) ESP-IDF ships `esp-pylib `_ as a core requirement. It collects utilities that are shared across Espressif's Python tools so that they behave consistently. When adding or modifying Python tooling, prefer these helpers over rolling your own — for example, emit output through its shared logger instead of calling ``print()`` yourself, and reuse its common error-handling and command-line building blocks rather than re-implementing them. Refer to the `esp-pylib README `_ for what is available and how to use it. + Configuring the Code Style for a Project Using EditorConfig ----------------------------------------------------------- diff --git a/docs/zh_CN/contribute/index.rst b/docs/zh_CN/contribute/index.rst index 68599d97d39..955e5a60b23 100644 --- a/docs/zh_CN/contribute/index.rst +++ b/docs/zh_CN/contribute/index.rst @@ -8,43 +8,43 @@ 如何贡献 -------------- -欢迎为 ESP-IDF 贡献内容，如修复问题、新增功能、添加文档等。你可通过 `Github Pull Requests `_ 提交你的贡献内容。 +欢迎为 ESP-IDF 贡献内容，如 bug 修复、新增功能、完善文档等。你可通过 `GitHub Pull Requests `_ 提交贡献内容。 准备工作 -------------- -在提交 Pull Request 前，请检查以下要点： +在提交 Pull Request 前，请先确认以下注意事项： -* 贡献内容是否完全是自己的成果，或已获得与 Apache License 2.0 兼容的开源许可？如果不是，我们不能接受该内容。了解更多信息，请见 :doc:`copyright-guide`。 +* 贡献内容是否完全由你独立创作，或已获得与 Apache License 2.0 兼容的开源许可？如不符合上述条件，我们将无法接受该贡献内容。如需了解更多信息，请参阅 :doc:`版权标头指南 `。 -* 要提交的代码是否符合 ESP-IDF :doc:`style-guide`？ +* 要提交的代码是否符合 :doc:`乐鑫 IoT 开发框架风格指南 `？ -* 如果贡献内容新增或修改了 Python 工具，是否遵循 :ref:`Python 代码风格 `，并在适用时复用 ``esp-pylib`` 提供的共享辅助代码？ +* 如果贡献内容新增或修改了 Python 工具，是否遵循 :ref:`Python 代码风格指南 `，并在适当的场景下复用了 ``esp-pylib`` 提供的公共辅助代码？ -* 是否安装了 ESP-IDF :doc:`pre-commit 钩子 `？ +* 是否安装了 ESP-IDF 项目的 :doc:`pre-commit 钩子 `？ -* 代码文档是否符合 :doc:`documenting-code` 的要求？ +* 代码文档是否符合 :doc:`编写代码文档 ` 的要求？ * 代码是否注释充分，便于读者理解其结构？ -* 是否为贡献的代码提供文档或示例？要写出好的示例，请参考 :idf:`examples` readme。 +* 贡献代码是否附有文档或示例？关于如何编写优质示例，请参阅 :idf:`examples` 中的 readme 文件。 -* 注释或文档是否以英语书写并表达清晰，不存在拼写或语法错误？ +* 注释和文档是否以英语书写，且表意清晰，无拼写或语法错误？ -* 欢迎贡献新的代码示例。了解更多信息，请参考 :doc:`creating-examples`。 +* 欢迎贡献代码示例，具体请参阅 :doc:`创建示例项目 `。 -* 如果需提交多个内容，是否将所有内容按照改动的类型（每个 pull request 对应一个主要改动）进行分组？是否有命名类似 “fixed typo” 的提交 `压缩到了此前的提交中 `_？ +* 若某份贡献包含多次代码提交 (commit)，是否按照改动的内容分组处理（每个 pull request 对应一项主要改动）？对于修改错字一类的次要 commit，是否已 `压缩合并到之前的 commit 中 `_？ -* 如不能确定上述任意内容，请提交 Pull Request，并向我们寻求反馈。 +* 如不能确定上述任意内容，请提交 Pull Request 并在评论区寻求反馈。 Pull Request 提交流程 -------------------------- -创建 Pull Request 后，PR 评论区中可能有一些关于该请求的讨论。 +创建 Pull Request 后，PR 评论区中可能会有一些讨论。 -Pull Request 准备好待合并时，首先会合并到我们的内部 git 系统中进行内部自动化测试。 +Pull Request 准备好待合并时，首先会合并到乐鑫的内部 Git 系统中进行自动化测试。 -测试流程通过后，你贡献的内容将合并到公共 GitHub 库。 +测试流程通过后，你的贡献内容将合并到公开 GitHub 仓库。 法律规范 ------------ diff --git a/docs/zh_CN/contribute/style-guide.rst b/docs/zh_CN/contribute/style-guide.rst index e35908a1f07..3845d94d3f2 100644 --- a/docs/zh_CN/contribute/style-guide.rst +++ b/docs/zh_CN/contribute/style-guide.rst @@ -8,11 +8,11 @@ 本风格指南旨在鼓励遵循 ESP-IDF 中通用的编码规范。 -风格指南提供了一系列规则，从而帮助创建可读性强、可维护性好且稳健的代码。编写与代码库风格一致的代码，可以促进阅读和理解；遵循相同的空格和换行规范，后期更改就不太会产生影响阅读的巨大差异；使用模块结构的通用模板并使用一致的编程语言特性，可以更好地理解代码行为。 +风格指南包含一系列规范准则，旨在编写出可读性高、可维护性强且稳定可靠的代码。编写与代码库编码风格统一的代码，能够提升代码的阅读与理解效率；统一空格、换行格式规范，可避免后续代码修改时产生大量晦涩难懂的差异内容；沿用通用的模块架构模式，规范各类语言特性的使用方式，能够方便其他开发人员理清代码的运行逻辑。 -本指南尽可能使规则保持简单，因此无法涵盖所有情况。某些时候，这些规则需要为代码的可读性、可维护性或稳健性让步。 +本指南尽可能简化各项规则，因此无法覆盖全部使用场景。部分场景下，需要为代码的可读性、可维护性与健壮性适当放宽规则要求。 -对 ESP-IDF 中使用的第三方代码进行修改时，请遵循该特定项目的编写方式，提出有用的更改，以合并到上游项目中。 +若需修改 ESP-IDF 所引入的第三方代码，请遵循该第三方项目自身的编码规范，同时提交具备实用价值的修改内容，以便并入上游开源项目。 C 语言代码格式化 ---------------- @@ -21,23 +21,23 @@ C 语言代码格式化 .. _style-guide-naming: -命名 -^^^^ +变量与函数命名 +^^^^^^^^^^^^^^ -* 任何仅在单个源文件中使用的变量或函数应声明为 ``static``。 -* 公共名称（非静态变量和函数）应使用每个组件或每个单元的前缀进行命名，以避免产生命名冲突，例如 ``esp_vfs_register()`` 或 ``esp_console_run()``。可以选择 ``esp_`` 作为乐鑫特定名称的前缀，但应与同一组件中的其他名称保持一致。 +* 仅在单个源文件中使用的变量与函数，需声明为 ``static``。 +* 公共名称（非静态变量、非静态函数）需添加对应组件或单元的专属前缀，规避命名冲突，例如 ``esp_vfs_register()``、 ``esp_console_run()``。乐鑫相关的专属名称可统一选用 ``esp_`` 作为前缀，但同一组件内其他名称的前缀规则需保持一致。 * 为了便于识别，静态变量应以 ``s_`` 为前缀。例如，``static bool s_invert``。 -* 除非名称会非常长，否则避免使用不必要的缩写（例如，将 ``data`` 缩写为 ``dat``）。 +* 避免不必要的缩写（例如将 ``data`` 简写为 ``dat``），除非不缩写会导致名称过长。 缩进 ^^^^ -每个缩进层级使用四个空格。不要使用制表符进行缩进。配置编辑器，确保在每次按下制表键时能打出四个空格。 +每个缩进层级使用四个空格。不要使用制表符进行缩进。配置编辑器，确保在每次按下制表键时输出四个空格。 -垂直空格 +垂直间距 ^^^^^^^^ -函数之间放置一行空行。不要在函数的开头或结尾处放置空行： +函数之间空一行。不要在函数的开头或结尾处空行。 .. code-block:: c @@ -57,12 +57,12 @@ C 语言代码格式化 } } -每行最多包含 120 个字符，只要不会严重影响可读性即可。 +只要不严重影响可读性，单行最大长度可接受 120 个字符。 水平空格 ^^^^^^^^ -- 记得在条件和循环关键字后加一个空格： +- 始终在条件和循环关键字后加一个空格： .. code-block:: c @@ -85,7 +85,7 @@ C 语言代码格式化 const int y = y0 + (x - x0) * (y1 - y0) / (x1 - x0); // 正确 - const int y = y0 + (x - x0)*(y1 - y0)/(x1 - x0); // 正确 + const int y = y0 + (x - x0)*(y1 - y0)/(x1 - x0); // 也可以 int y_cur = -y; // 正确 ++y_cur; @@ -94,7 +94,7 @@ C 语言代码格式化 ``.`` 和 ``->`` 运算符前后不需要加空格。 -- 有时在一行中添加水平空格可以提高代码的可读性。例如，可以添加空格以对齐函数参数： +- 有时，在代码行内添加横向空格能够提升代码的可读性。例如，你可以通过添加空格来对齐函数参数： .. code-block:: c @@ -103,33 +103,33 @@ C 语言代码格式化 esp_rom_gpio_connect_in_signal(PIN_CAM_HREF, I2S0I_H_ENABLE_IDX, false); esp_rom_gpio_connect_in_signal(PIN_CAM_PCLK, I2S0I_DATA_IN15_IDX, false); -但是请注意，如果新写一行，将较长的标识符作为第一个参数（例如，``PIN_CAM_VSYNC``），这条规则将不再适用，其他行也不得不重新进行对齐，提交记录中将出现无意义的更改。 +但需要注意的是，如果有人新增一行代码，并将更长的标识符作为首个参数（例如 ``PIN_CAM_VSYNC``），该标识符将无法适配原有格式。因此需要重新调整其他代码行的对齐格式，给本次代码提交引入大量无实际意义的修改内容。 -因此，请谨慎使用水平对齐，尤其是在后期可能会向列表中添加新行的情况下。 +因此，请谨慎使用横向对齐，尤其是在后期可能会向列表中添加新行的情况下。 -切勿使用制表符进行水平对齐。 +切勿使用制表符进行横向对齐。 -切勿在行末以空格结尾。 +切勿在行尾添加额外的空白字符。 大括号 ^^^^^^ -- 函数定义应将大括号放在单独的一行： +- 函数定义需将大括号放在单独的一行： .. code-block:: c - // 这是正确的： + // 正确： void function(int arg) { } - // 这是错误的： + // 错误： void function(int arg) { } -- 在函数内部，请将左大括号、条件及循环语句放在同一行： +- 在函数内部，左大括号需与条件语句、循环语句放在同一行： .. code-block:: c @@ -143,22 +143,22 @@ C 语言代码格式化 注释 ^^^^ -使用 ``//`` 进行单行注释；多行注释既可以在每行使用 ``//``，也可以使用 ``/* */`` 块。 +使用 ``//`` 进行单行注释；多行注释既可使用 ``//`` 逐行注释，也可使用 ``/* */`` 注释块。 -尽管与格式无直接关系，但以下是一些关于如何有效使用注释的注意事项。 +尽管与格式化无关，但以下是一些关于如何有效使用注释的注意事项。 -- 不要使用单行注释来禁用某些功能： +- 不要使用单行注释来禁用功能： .. code-block:: c void init_something() { setup_dma(); - // load_resources(); // 读者会疑惑为什么此处被置于注释中。 + // load_resources(); // 读者会疑惑为什么此处被注释。 start_timer(); } -- 如果不再需要某些代码，请将其完全删除。这些代码之后可以随时在相关文件的 git 历史记录中查到。如果出于某些临时原因禁用了部分函数调用，并且打算之后将其恢复，请在相邻行添加解释： +- 如果不再需要某些代码，请将其完全删除。这些代码之后可以随时在相关文件的 git 历史记录中查到。如果出于某些临时原因禁用了部分函数调用，并且打算之后将其恢复，请在相邻行添加说明： .. code-block:: c @@ -170,9 +170,9 @@ C 语言代码格式化 start_timer(); } -- 上述规则同样适用于 ``#if 0 ... #endif`` 块。如果不再需要代码块，请将其完全删除。否则，请添加注释以说明禁用该代码块的原因。请不要使用 ``#if 0 ... #endif`` 或注释来存储将来可能需要的代码片段。 +- 上述规则同样适用于 ``#if 0 ... #endif`` 块。如果不再需要代码块，请将其完全删除。否则，请添加注释以说明禁用该代码块的原因。不要使用 ``#if 0 ... #endif`` 或注释来存放未来可能用到的代码片段。 -- 不要添加有关作者和更改日期的琐碎注释，可以直接使用 git 来查找修改人及修改内容等相关信息。例如，类似下文的注释不仅没添加任何有用的信息，还会使代码变得杂乱： +- 不要添加有关作者和更改日期的琐碎注释。可以直接使用 Git 来查找修改人及修改内容等相关信息。例如，类似下文的注释不仅没添加任何有用的信息，还会使代码变得杂乱无章： .. code-block:: c @@ -192,17 +192,17 @@ C 语言代码格式化 提交内容只能包含以 LF（Unix 风格）为行结束符的文件。 -Windows 用户可以通过设置 ``core.autocrlf``，将 git 配置为在本地检出以 CRLF（Windows 风格）为行结束符的文件，但提交时转换为以 LF 为行结束符。Github 中有一个 `文档 `_ 介绍了如何配置此选项。 +Windows 用户可以通过设置 ``core.autocrlf`` 参数，让 Git 在本地检出文件时使用 Windows 风格的 CRLF 行结束符，提交代码时自动转换为 LF 行结束符。GitHub 官方提供了相关配置的 `说明文档 `_。 -如果分支提交的信息在无意中带有 LF 行结束符，可以在 MSYS2 或 Unix 终端中运行以下命令，将其转换为 Unix 风格（请先切换到 IDF 工作目录并检查当前所在分支是否正确）： +如果你的分支中意外存在一些提交引入了换行符 (LF) 结尾格式，你可以在 MSYS2 或类 Unix 终端中执行以下命令将其转换为 Unix 格式（需提前切换至 IDF 工作目录，并确保当前已切换到正确的分支）： .. code-block:: bash git rebase --exec 'git diff-tree --no-commit-id --name-only -r HEAD | xargs dos2unix && git commit -a --amend --no-edit --allow-empty' master -请注意，上述命令基于 master 进行 rebase，若要基于其他分支进行 rebase，请更改命令结尾的分支名称。 +请注意，上述示例命令是基于 master 分支执行变基操作；若需基于其他分支执行变基，请修改命令末尾对应的分支名称。 -要更新单次提交中的文件行结束符，可以先运行 ``dos2unix FILENAME``，再运行 ``git commit --amend``。 +如果仅需要修改单次提交，可以先运行 ``dos2unix FILENAME``，再运行 ``git commit --amend`` 更新。 代码格式化 ^^^^^^^^^^ @@ -251,17 +251,17 @@ ESP-IDF 使用 Astyle 来格式化源代码。配置存储在 :project_file:`too 断言 ^^^^ -使用 ``assert.h`` 中定义的标准 C 函数 ``assert()`` 来检查源代码中应该为真的条件。在默认配置中，若断言条件返回 ``false`` 或 ``0``，则将调用 ``abort()`` 并触发 :doc:`严重错误 `。 +标准 C 语言的 ``assert()`` 函数定义于头文件 ``assert.h`` 中，该函数用于检查源代码中理应成立的条件。在默认配置下，若断言条件返回 ``false`` 或 ``0``，程序会调用 ``abort()`` 函数并触发 :doc:`严重错误 `。 -``assert()`` 只用于检测那些无法修复的错误，这些错误因严重的内部逻辑漏洞或数据损坏而产生，导致程序无法继续运行。对于可修复的错误（如因无效外部输入而产生的错误），:doc:`应返回一个错误值 `。 +``assert()`` 只用于检测那些无法修复的错误，这些错误因严重的内部逻辑漏洞或数据损坏而产生，导致程序无法继续运行。对于可修复的错误（如因无效外部输入而产生的错误），应当返回错误值，相关说明可参考文档：:doc:`错误处理 `。 .. note:: 当断言一个类型为 ``esp_err_t`` 的值等于 ``ESP_OK`` 时，应使用 :ref:`esp-error-check-macro` 而不是 ``assert()``。 -可以将 ESP-IDF 项目配置为禁用断言（详见 :ref:`CONFIG_COMPILER_OPTIMIZATION_ASSERTION_LEVEL`）。因此，在 ``assert()`` 语句中调用的函数不应有副作用。 +可以将 ESP-IDF 项目配置为禁用断言（详见 :ref:`CONFIG_COMPILER_OPTIMIZATION_ASSERTION_LEVEL`）。此时在 ``assert()`` 语句中调用的函数不应有副作用。 -还需要使用特定技术来避免禁用断言时出现“变量定义但未使用”的警告，这种警告通常由以下代码模式引起： +当断言功能被禁用时，还需要采用特定的技术手段来避免出现“变量定义但未使用”的警告，这种警告通常由以下代码模式引起： .. code-block:: c @@ -270,7 +270,7 @@ ESP-IDF 使用 Astyle 来格式化源代码。配置存储在 :project_file:`too 一旦 ``assert`` 被优化掉，将不再使用 ``res`` 值，编译器会对此发出警告。但即使禁用了断言，仍必须调用 ``do_something()`` 函数。 -当变量在单个语句中声明并初始化时，最好在新的一行上将其转换为 ``void``。编译器将不再发出警告，且变量仍可在最终的二进制文件中被优化掉： +当变量在单个语句中声明并初始化时，最好在新的一行将其转换为 ``void``。编译器将不再发出警告，且变量仍可在最终的二进制文件中被优化删除： .. code-block:: c @@ -278,7 +278,7 @@ ESP-IDF 使用 Astyle 来格式化源代码。配置存储在 :project_file:`too assert(res == 0); (void)res; -如果变量是单独声明的，例如该变量被用于多个断言，则可以使用 GCC 属性 ``__attribute__((unused))`` 来声明它。编译器将不再发出任何有关未使用变量的警告，且变量仍可被优化掉： +如果变量是单独声明的，例如该变量被用于多个断言，则可以使用 GCC 属性 ``__attribute__((unused))`` 来声明它。编译器将不再发出任何有关未使用变量的警告，且变量仍可被优化删除： .. code-block:: c @@ -294,7 +294,7 @@ ESP-IDF 使用 Astyle 来格式化源代码。配置存储在 :project_file:`too 头文件保护 ---------- -所有面向公众的头文件应具有预处理器保护。推荐使用 pragma： +所有公共头文件应具有预处理器保护。推荐使用 pragma： .. code-block:: c @@ -331,7 +331,7 @@ ESP-IDF 使用 Astyle 来格式化源代码。配置存储在 :project_file:`too include 语句 ------------ -编写 ``#include`` 语句时，请尝试保持以下顺序： +编写 ``#include`` 语句时，需保持以下顺序： * C 标准库头文件。 * 其他 POSIX 标准头文件及其常见扩展（如 ``sys/queue.h``）。 @@ -348,7 +348,7 @@ include 语句 C++ 代码格式化 -------------- -前文提到的 C 语言代码格式化规则同样适用于 C++ 代码格式化。如果这些规则不够，请遵循以下补充规则。 +前文提到的 C 语言代码格式化规则同样适用于 C++ 代码格式化。如果这些规则不足以满足需求，可遵循以下补充规则。 文件命名 ^^^^^^^^ @@ -358,18 +358,18 @@ C++ 头文件的扩展名为 ``.hpp``。C++ 源文件的扩展名为 ``.cpp``。 命名 ^^^^ -* **类和结构体** 名称应使用首字母大写的 ``驼峰命名法`` (CamelCase)。成员变量和方法应使用 ``蛇形命名法`` (snake_case)。若 ``驼峰命名法`` 严重降低了可读性（例如命名 ``GPIOOutput`` 时），可允许使用下划线 ``_`` （例如，``GPIO_Output``），从而增强可读性。 +* **类和结构体** 名称应使用首字母大写的 ``驼峰命名法`` (CamelCase)。成员变量和方法应使用 ``蛇形命名法`` (snake_case)。若 ``驼峰命名法`` 会严重降低可读性（例如命名 ``GPIOOutput`` 时），可允许使用下划线 ``_`` （例如 ``GPIO_Output``）增强可读性。 * **命名空间** 应使用小写的 ``蛇形命名法``。 * **模板** 应在函数声明的上一行进行指定。 -* 面向对象编程 (OOP) 中的接口命名不应使用后缀 ``...Interface``。这种命名方式使得将来从普通类中提取接口或将接口转换为类时，更加容易实现而不会造成破坏性变更。 +* 面向对象编程 (OOP) 中的接口命名不应使用后缀 ``...Interface``。采用该命名方式，后续无论是从普通类中抽取接口，还是将接口改造为普通类，都能顺畅完成调整，不会引发破坏性变更。 类成员顺序 ^^^^^^^^^^ 按照优先顺序： -* 先放置公共成员，然后是受保护成员，最后是私有成员。没有成员的公共、受保护或私有部分应省略。 -* 先放置构造函数/析构函数，然后是成员函数，最后是成员变量。 +* 依次声明公共成员、受保护成员、私有成员；若某一访问权限下没有成员，则省略该部分的声明。 +* 先定义构造函数与析构函数，再定义成员函数，最后声明成员变量。 例如： @@ -400,7 +400,7 @@ C++ 头文件的扩展名为 ``.hpp``。C++ 源文件的扩展名为 ``.cpp``。 ^^^^ * 在命名空间内部不要缩进。 -* 将 ``public``、``protected`` 和 ``private`` 标签的缩进级别与相应 ``class`` 标签的缩进级别保持一致。 +* ``public``、 ``protected`` 与 ``private`` 标签的缩进应与相应 ``class`` 标签的缩进保持一致。 简单示例 ^^^^^^^^ @@ -480,8 +480,8 @@ CMake 代码风格 -------------- - 使用四个空格缩进。 -- 每行最多包含 120 个字符。当分割行时，尽量注重可读性（例如，在单独的行上进行关键字匹配或参数匹配）。 -- 在 ``endforeach()``、``endif()`` 等可选括号中不要添加任何内容。 +- 每行最多包含 120 个字符。需要换行时，应尽量兼顾可读性，例如将关键字与参数组放置在单独一行中。 +- 在 ``endforeach()``、 ``endif()`` 等可选括号中不要添加任何内容。 - 使用小写 (``with_underscores``) 来命名指令、函数和宏。 - 对于局部变量，使用小写 (``with_underscores``)。 - 对于全局变量，使用大写 (``WITH_UNDERSCORES``)。 @@ -492,22 +492,23 @@ CMake 代码风格 Python 代码风格 --------------- -ESP-IDF 的大部分工具——``idf.py`` 及其子命令、构建系统辅助脚本，以及 :idf:`tools` 目录下的脚本——均使用 Python 编写。为保证贡献内容的可移植性，新增的 Python 代码应能在 ESP-IDF 支持的所有 Python 版本上运行：从 :doc:`快速入门 ` 中所述的最低支持版本，到最新发布的 Python 版本。请避免使用在该版本范围内并非普遍可用的语法或标准库特性。 +ESP-IDF 的大部分工具，即 ``idf.py`` 及其子命令、构建系统辅助脚本、:idf:`tools` 目录下的脚本，均使用 Python 编写。为保证贡献内容的可移植性，新增的 Python 代码应能在 ESP-IDF 支持的所有 Python 版本上运行，即 :doc:`快速入门 ` 中所述的最低支持版本，到最新发布的 Python 版本。请避免依赖此版本范围内尚不普遍支持的语法或标准库特性。 代码检查与格式化 ^^^^^^^^^^^^^^^^ -Python 代码由 `Ruff `_ 进行检查和格式化，并由 `mypy `_ 进行类型检查，相关配置位于 :project_file:`ruff.toml` 和 :project_file:`.mypy.ini`。你无需记住每一条具体规则：只需在提交前安装 :doc:`pre-commit 钩子 `，这些工具便会在每次提交时自动运行，使你的改动与代码库的其余部分保持一致。 +Python 代码由 `Ruff `_ 进行检查和格式化，并由 `mypy `_ 进行类型检查，相关配置位于 :project_file:`ruff.toml` 和 :project_file:`.mypy.ini`。无需记住这些规则，仅需在提交前安装 :doc:`pre-commit 钩子 ` （安装一次即可），此后每次提交时就会自动运行这些检查工具，确保改动风格与代码库整体保持一致。 依赖项 ^^^^^^^^ -Python 依赖项在 :idf:`tools/requirements` 目录下的 requirements 文件中声明。其中只需列出软件包名称——请勿在这些文件中固定版本号。版本约束由位于 ESP-IDF 仓库之外的独立约束 (constraint) 文件单独维护，因此在 requirements 文件中写死版本通常是错误的做法。 +Python 依赖项在 :idf:`tools/requirements` 目录下的 requirements 文件中声明。列出软件包名称即可，请勿在这些文件中固定版本号。版本约束由位于 ESP-IDF 仓库之外的独立约束 (constraint) 文件单独维护，因此在 requirements 文件中写死版本号通常是错误的做法。 复用共享代码 (esp-pylib) ^^^^^^^^^^^^^^^^^^^^^^^^ -ESP-IDF 将 `esp-pylib `_ 作为核心依赖项一同提供。它汇集了在乐鑫各 Python 工具间共享的实用工具，使这些工具的行为保持一致。在新增或修改 Python 工具时，应优先使用这些辅助代码，而非自行实现——例如，应通过其共享的日志记录器输出信息，而不要自己调用 ``print()``，并复用其通用的错误处理与命令行构建模块，而非重新实现。关于可用功能及其用法，请参阅 `esp-pylib README `_。 +ESP-IDF 将 `esp-pylib `_ 作为核心依赖项一同提供。该库整合了乐鑫各类 Python 工具共用的实用工具集，能够保障不同工具的行为保持统一。在新增或迭代修改 Python 工具的过程中，应优先复用该库中的各类辅助代码，而非自行实现。例如，须使用此库内置的共享日志记录器输出日志信息，而不要自行调用 ``print()`` 函数；同时，复用库中通用的错误处理、命令行构建模块，不要重新实现。如需了解该库支持的全部功能及具体使用方式，请参阅 `esp-pylib README `_。 + 使用 EditorConfig 配置项目代码风格 ---------------------------------- @@ -538,7 +539,7 @@ FreeRTOS 代码文档 -------- -请参阅此处的指南：:doc:`documenting-code`。 +请参阅 :doc:`documenting-code`。 结构体 ------