mirror of
https://github.com/espressif/esp-idf.git
synced 2026-10-02 11:10:54 +03:00
docs: Update contribution docs
This commit is contained in:
renpeiying
@@ -8,43 +8,43 @@
|
||||
如何贡献
|
||||
--------------
|
||||
|
||||
欢迎为 ESP-IDF 贡献内容，如修复问题、新增功能、添加文档等。你可通过 `Github Pull Requests <https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests>`_ 提交你的贡献内容。
|
||||
欢迎为 ESP-IDF 贡献内容，如 bug 修复、新增功能、完善文档等。你可通过 `GitHub Pull Requests <https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests>`_ 提交贡献内容。
|
||||
|
||||
准备工作
|
||||
--------------
|
||||
|
||||
在提交 Pull Request 前，请检查以下要点：
|
||||
在提交 Pull Request 前，请先确认以下注意事项：
|
||||
|
||||
* 贡献内容是否完全是自己的成果，或已获得与 Apache License 2.0 兼容的开源许可？如果不是，我们不能接受该内容。了解更多信息，请见 :doc:`copyright-guide`。
|
||||
* 贡献内容是否完全由你独立创作，或已获得与 Apache License 2.0 兼容的开源许可？如不符合上述条件，我们将无法接受该贡献内容。如需了解更多信息，请参阅 :doc:`版权标头指南 <copyright-guide>`。
|
||||
|
||||
* 要提交的代码是否符合 ESP-IDF :doc:`style-guide`？
|
||||
* 要提交的代码是否符合 :doc:`乐鑫 IoT 开发框架风格指南 <style-guide>`？
|
||||
|
||||
* 如果贡献内容新增或修改了 Python 工具，是否遵循 :ref:`Python 代码风格 <python-code-style>`，并在适用时复用 ``esp-pylib`` 提供的共享辅助代码？
|
||||
* 如果贡献内容新增或修改了 Python 工具，是否遵循 :ref:`Python 代码风格指南 <python-code-style>`，并在适当的场景下复用了 ``esp-pylib`` 提供的公共辅助代码？
|
||||
|
||||
* 是否安装了 ESP-IDF :doc:`pre-commit 钩子 <install-pre-commit-hook>`？
|
||||
* 是否安装了 ESP-IDF 项目的 :doc:`pre-commit 钩子 <install-pre-commit-hook>`？
|
||||
|
||||
* 代码文档是否符合 :doc:`documenting-code` 的要求？
|
||||
* 代码文档是否符合 :doc:`编写代码文档 <documenting-code>` 的要求？
|
||||
|
||||
* 代码是否注释充分，便于读者理解其结构？
|
||||
|
||||
* 是否为贡献的代码提供文档或示例？要写出好的示例，请参考 :idf:`examples` readme。
|
||||
* 贡献代码是否附有文档或示例？关于如何编写优质示例，请参阅 :idf:`examples` 中的 readme 文件。
|
||||
|
||||
* 注释或文档是否以英语书写并表达清晰，不存在拼写或语法错误？
|
||||
* 注释和文档是否以英语书写，且表意清晰，无拼写或语法错误？
|
||||
|
||||
* 欢迎贡献新的代码示例。了解更多信息，请参考 :doc:`creating-examples`。
|
||||
* 欢迎贡献代码示例，具体请参阅 :doc:`创建示例项目 <creating-examples>`。
|
||||
|
||||
* 如果需提交多个内容，是否将所有内容按照改动的类型（每个 pull request 对应一个主要改动）进行分组？是否有命名类似 “fixed typo” 的提交 `压缩到了此前的提交中 <https://eli.thegreenplace.net/2014/02/19/squashing-github-pull-requests-into-a-single-commit/>`_？
|
||||
* 若某份贡献包含多次代码提交 (commit)，是否按照改动的内容分组处理（每个 pull request 对应一项主要改动）？对于修改错字一类的次要 commit，是否已 `压缩合并到之前的 commit 中 <https://eli.thegreenplace.net/2014/02/19/squashing-github-pull-requests-into-a-single-commit/>`_？
|
||||
|
||||
* 如不能确定上述任意内容，请提交 Pull Request，并向我们寻求反馈。
|
||||
* 如不能确定上述任意内容，请提交 Pull Request 并在评论区寻求反馈。
|
||||
|
||||
Pull Request 提交流程
|
||||
--------------------------
|
||||
|
||||
创建 Pull Request 后，PR 评论区中可能有一些关于该请求的讨论。
|
||||
创建 Pull Request 后，PR 评论区中可能会有一些讨论。
|
||||
|
||||
Pull Request 准备好待合并时，首先会合并到我们的内部 git 系统中进行内部自动化测试。
|
||||
Pull Request 准备好待合并时，首先会合并到乐鑫的内部 Git 系统中进行自动化测试。
|
||||
|
||||
测试流程通过后，你贡献的内容将合并到公共 GitHub 库。
|
||||
测试流程通过后，你的贡献内容将合并到公开 GitHub 仓库。
|
||||
|
||||
法律规范
|
||||
------------
|
||||
|
||||
@@ -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 中有一个 `文档 <https://docs.github.com/cn/get-started/getting-started-with-git/configuring-git-to-handle-line-endings?platform=windows>`_ 介绍了如何配置此选项。
|
||||
Windows 用户可以通过设置 ``core.autocrlf`` 参数，让 Git 在本地检出文件时使用 Windows 风格的 CRLF 行结束符，提交代码时自动转换为 LF 行结束符。GitHub 官方提供了相关配置的 `说明文档 <https://docs.github.com/cn/get-started/getting-started-with-git/configuring-git-to-handle-line-endings?platform=windows>`_。
|
||||
|
||||
如果分支提交的信息在无意中带有 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:`严重错误 </api-guides/fatal-errors>`。
|
||||
标准 C 语言的 ``assert()`` 函数定义于头文件 ``assert.h`` 中，该函数用于检查源代码中理应成立的条件。在默认配置下，若断言条件返回 ``false`` 或 ``0``，程序会调用 ``abort()`` 函数并触发 :doc:`严重错误 </api-guides/fatal-errors>`。
|
||||
|
||||
``assert()`` 只用于检测那些无法修复的错误，这些错误因严重的内部逻辑漏洞或数据损坏而产生，导致程序无法继续运行。对于可修复的错误（如因无效外部输入而产生的错误），:doc:`应返回一个错误值 </api-guides/error-handling>`。
|
||||
``assert()`` 只用于检测那些无法修复的错误，这些错误因严重的内部逻辑漏洞或数据损坏而产生，导致程序无法继续运行。对于可修复的错误（如因无效外部输入而产生的错误），应当返回错误值，相关说明可参考文档：:doc:`错误处理 </api-guides/error-handling>`。
|
||||
|
||||
.. 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:`快速入门 </get-started/start-project>` 中所述的最低支持版本，到最新发布的 Python 版本。请避免使用在该版本范围内并非普遍可用的语法或标准库特性。
|
||||
ESP-IDF 的大部分工具，即 ``idf.py`` 及其子命令、构建系统辅助脚本、:idf:`tools` 目录下的脚本，均使用 Python 编写。为保证贡献内容的可移植性，新增的 Python 代码应能在 ESP-IDF 支持的所有 Python 版本上运行，即 :doc:`快速入门 </get-started/start-project>` 中所述的最低支持版本，到最新发布的 Python 版本。请避免依赖此版本范围内尚不普遍支持的语法或标准库特性。
|
||||
|
||||
代码检查与格式化
|
||||
^^^^^^^^^^^^^^^^
|
||||
|
||||
Python 代码由 `Ruff <https://docs.astral.sh/ruff/>`_ 进行检查和格式化，并由 `mypy <https://www.mypy-lang.org/>`_ 进行类型检查，相关配置位于 :project_file:`ruff.toml` 和 :project_file:`.mypy.ini`。你无需记住每一条具体规则：只需在提交前安装 :doc:`pre-commit 钩子 <install-pre-commit-hook>`，这些工具便会在每次提交时自动运行，使你的改动与代码库的其余部分保持一致。
|
||||
Python 代码由 `Ruff <https://docs.astral.sh/ruff/>`_ 进行检查和格式化，并由 `mypy <https://www.mypy-lang.org/>`_ 进行类型检查，相关配置位于 :project_file:`ruff.toml` 和 :project_file:`.mypy.ini`。无需记住这些规则，仅需在提交前安装 :doc:`pre-commit 钩子 <install-pre-commit-hook>` （安装一次即可），此后每次提交时就会自动运行这些检查工具，确保改动风格与代码库整体保持一致。
|
||||
|
||||
依赖项
|
||||
^^^^^^^^
|
||||
|
||||
Python 依赖项在 :idf:`tools/requirements` 目录下的 requirements 文件中声明。其中只需列出软件包名称——请勿在这些文件中固定版本号。版本约束由位于 ESP-IDF 仓库之外的独立约束 (constraint) 文件单独维护，因此在 requirements 文件中写死版本通常是错误的做法。
|
||||
Python 依赖项在 :idf:`tools/requirements` 目录下的 requirements 文件中声明。列出软件包名称即可，请勿在这些文件中固定版本号。版本约束由位于 ESP-IDF 仓库之外的独立约束 (constraint) 文件单独维护，因此在 requirements 文件中写死版本号通常是错误的做法。
|
||||
|
||||
复用共享代码 (esp-pylib)
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
ESP-IDF 将 `esp-pylib <https://github.com/espressif/esp-pylib>`_ 作为核心依赖项一同提供。它汇集了在乐鑫各 Python 工具间共享的实用工具，使这些工具的行为保持一致。在新增或修改 Python 工具时，应优先使用这些辅助代码，而非自行实现——例如，应通过其共享的日志记录器输出信息，而不要自己调用 ``print()``，并复用其通用的错误处理与命令行构建模块，而非重新实现。关于可用功能及其用法，请参阅 `esp-pylib README <https://github.com/espressif/esp-pylib>`_。
|
||||
ESP-IDF 将 `esp-pylib <https://github.com/espressif/esp-pylib>`_ 作为核心依赖项一同提供。该库整合了乐鑫各类 Python 工具共用的实用工具集，能够保障不同工具的行为保持统一。在新增或迭代修改 Python 工具的过程中，应优先复用该库中的各类辅助代码，而非自行实现。例如，须使用此库内置的共享日志记录器输出日志信息，而不要自行调用 ``print()`` 函数；同时，复用库中通用的错误处理、命令行构建模块，不要重新实现。如需了解该库支持的全部功能及具体使用方式，请参阅 `esp-pylib README <https://github.com/espressif/esp-pylib>`_。
|
||||
|
||||
|
||||
使用 EditorConfig 配置项目代码风格
|
||||
----------------------------------
|
||||
@@ -538,7 +539,7 @@ FreeRTOS
|
||||
代码文档
|
||||
--------
|
||||
|
||||
请参阅此处的指南：:doc:`documenting-code`。
|
||||
请参阅 :doc:`documenting-code`。
|
||||
|
||||
结构体
|
||||
------
|
||||
|
||||
Reference in New Issue
Block a user