代码风格规范

在给 Godot 的源代码做贡献时，你需要遵循下面概述的样式规范。其中一些是通过持续集成过程进行检查的，评审人员将要求你修复潜在的问题，因此最好按照下面概述的方式设置系统，以确保所有提交都遵循规范。

C++ 和 Objective-C

There are no written guidelines, but the code style agreed upon by the developers is enforced via the clang-format code beautifier, which takes care for you of all our conventions. To name a few:

  • 缩进和对齐都是基于制表符的（分别是一个和两个制表符）

  • 数学和赋值运算符以及逗号后面有一个空格

  • 指针和引用运算符附加到变量标识符，而不是类型名称

  • 有关头文件的引入，请参见下文

Clang 格式使用的规则在 Godot 仓库的 .clang-format 文件中进行了概述。

As long as you ensure that your style matches the surrounding code and that you’re not introducing trailing whitespace or space-based indentation, you should be fine. If you plan to contribute regularly, however, we strongly advise that you set up clang-format locally to check and automatically fix all your commits.

警告

Godot’s code style should not be applied to third-party code, i.e. that is included in Godot’s source tree but was not written specifically for our project. Such code usually comes from different upstream projects with their own style guides (or lack thereof), and don’t want to introduce differences that would make syncing with upstream repositories harder.

第三方代码通常包含在 thirdparty/ 文件夹中, 因此可以很容易地从格式化脚本中排除. 在极少数情况下, 第三方代码片段需要直接包含在Godot文件中, 你可以使用 /* clang-format off */ 和 /* clang-format on */ 来告诉clang-format忽略某块儿的代码.

参见

这些规范只涉及代码的格式化。拉取请求中所允许的语言特性列表请参阅 C++ 使用规范。

在本地使用 clang-format

You need to use clang-format 17 to be compatible with Godot’s format. Later versions might be suitable, but previous versions may not support all used options, or format some things differently, leading to style issues in pull requests.

预提交钩子

为了便于使用，我们提供了基于 pre-commit Python 框架的 Git 钩子，可以对你的所有提交自动运行 clang-format，同时确保使用的是正确版本的 clang-format。设置方法是这样的：

  1. pip install pre-commit
  2. pre-commit install

你还可以使用 pre-commit run 手动运行这个钩子。

备注

Previously, we supplied a hook in the folder misc/hooks. If you copied the script manually, these hooks should still work, but symlinks will be broken. If you are using the new system, run rm .git/hooks/* to remove the old hooks that are no longer needed.

安装

以下是如何安装 clang-format：

  • Linux: It will usually be available out-of-the-box with the clang toolchain packaged by your distribution. If your distro version is not the required one, you can download a pre-compiled version from the LLVM website, or if you are on a Debian derivative, use the upstream repos.

  • macOS and Windows: You can download precompiled binaries from the LLVM website. You may need to add the path to the binary’s folder to your system’s PATH environment variable to be able to call clang-format out of the box.

然后, 你就有不同的可能性将clang-format应用于你的更改:

手动使用

You can apply clang-format manually for one or more files with the following command:

  1. clang-format -i <path/to/file(s)>

  • -i 表示更改应直接写入文件(默认情况下,clang-format只会将固定版本输出到终端).

  • 该路径可以指向几个文件, 一个接一个, 也可以使用如在典型的Unix shell中的通配符. 在通配时要小心, 以免对Godot树中的已编译对象(.o和.a文件)运行clang格式. 因此, 最好使用 core/*. {cpp,h} 而不是 core/*.

IDE插件

Most IDEs or code editors have beautifier plugins that can be configured to run clang-format automatically, for example, each time you save a file.

以下是一些IDE的美化插件的非详尽列表:

(Pull requests are welcome to extend this list with tested plugins.)

头文件的引入

当添加新的C++或Objective-C文件或在现有文件中引入新的标头时, 应遵循以下规则:

  • 文件中的第一行应该是Godot的版权标头和MIT许可证, 从另一个文件复制粘贴. 确保调整文件名.

  • 在 .h 头文件中, 引入防护应该与 FILENAME_H 形式一起使用.

  • 在 .cpp 文件(如 filename.cpp )中, 第一个引入应该是声明类的那个(例如 #include "filename.h"), 然后使用空行分隔.

  • 然后来自Godot自己的代码库的标头, 按字母顺序(由 clang-format 强制)引入, 并具有相对于根文件夹的路径. 这些引入应该用引号来完成, 例如 #include "core/object.h". 然后,Godot标头引入的块应用一个空行以进行分隔.

  • 最后, 第三方头文件(无论是来自 thirdparty 还是来自系统的包含路径)接下来, 应该用 < and > 符号包含, 例如 #include <png.h> . 第三方头文件块的后面也应该有一个空行来分隔.

  • Godot和第三方标头应包含在需要它们的文件中, 即, 如果在声明性代码中使用, 则在 .h 标头中；如果仅在命令性代码中使用, 则在 .cpp 中.

示例：

  1. /**************************************************************************/
  2. /*  my_new_file.h                                                         */
  3. /**************************************************************************/
  4. /*                         This file is part of:                          */
  5. /*                             GODOT ENGINE                               */
  6. /*                        https://godotengine.org                         */
  7. /**************************************************************************/
  8. /* Copyright (c) 2014-present Godot Engine contributors (see AUTHORS.md). */
  9. /* Copyright (c) 2007-2014 Juan Linietsky, Ariel Manzur.                  */
  10. /*                                                                        */
  11. /* Permission is hereby granted, free of charge, to any person obtaining  */
  12. /* a copy of this software and associated documentation files (the        */
  13. /* "Software"), to deal in the Software without restriction, including    */
  14. /* without limitation the rights to use, copy, modify, merge, publish,    */
  15. /* distribute, sublicense, and/or sell copies of the Software, and to     */
  16. /* permit persons to whom the Software is furnished to do so, subject to  */
  17. /* the following conditions:                                              */
  18. /*                                                                        */
  19. /* The above copyright notice and this permission notice shall be         */
  20. /* included in all copies or substantial portions of the Software.        */
  21. /*                                                                        */
  22. /* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,        */
  23. /* EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF     */
  24. /* MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. */
  25. /* IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY   */
  26. /* CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,   */
  27. /* TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE      */
  28. /* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.                 */
  29. /**************************************************************************/
  31. #ifndef MY_NEW_FILE_H
  32. #define MY_NEW_FILE_H
  34. #include "core/hash_map.h"
  35. #include "core/list.h"
  36. #include "scene/gui/control.h"
  38. #include <png.h>
  40. ...
  42. #endif // MY_NEW_FILE_H
  1. /**************************************************************************/
  2. /*  my_new_file.cpp                                                       */
  3. /**************************************************************************/
  4. /*                         This file is part of:                          */
  5. /*                             GODOT ENGINE                               */
  6. /*                        https://godotengine.org                         */
  7. /**************************************************************************/
  8. /* Copyright (c) 2014-present Godot Engine contributors (see AUTHORS.md). */
  9. /* Copyright (c) 2007-2014 Juan Linietsky, Ariel Manzur.                  */
  10. /*                                                                        */
  11. /* Permission is hereby granted, free of charge, to any person obtaining  */
  12. /* a copy of this software and associated documentation files (the        */
  13. /* "Software"), to deal in the Software without restriction, including    */
  14. /* without limitation the rights to use, copy, modify, merge, publish,    */
  15. /* distribute, sublicense, and/or sell copies of the Software, and to     */
  16. /* permit persons to whom the Software is furnished to do so, subject to  */
  17. /* the following conditions:                                              */
  18. /*                                                                        */
  19. /* The above copyright notice and this permission notice shall be         */
  20. /* included in all copies or substantial portions of the Software.        */
  21. /*                                                                        */
  22. /* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,        */
  23. /* EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF     */
  24. /* MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. */
  25. /* IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY   */
  26. /* CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,   */
  27. /* TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE      */
  28. /* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.                 */
  29. /**************************************************************************/
  31. #include "my_new_file.h"
  33. #include "core/math/math_funcs.h"
  34. #include "scene/gui/line_edit.h"
  36. #include <zlib.h>
  37. #include <zstd.h>

Java

Godot的Java代码(主要在 platform/android 中)也是通过 clang-format 来执行的, 所以请看上面的说明来设置它. 请记住, 本风格规则只适用于Godot编写和维护的代码, 而不是第三方代码, 如 java/src/com/google 子文件夹.

Python

Godot的SCons构建系统是用Python编写的, 源代码树中包含的各种脚本也使用Python.

For those, we use the Ruff linter and code formatter.

本地使用 ruff

首先你需要安装 Ruff。Ruff 需要 Python 3.7+ 才能运行。

安装

下面介绍如何安装 ruff：

  1. pip3 install ruff --user

这样就可以将 ruff 应用到你的修改了：

手动使用

你可以使用以下命令将 ruff 手动应用于一个或多个文件：

  1. ruff -l 120 <path/to/file(s)>

  • -l 120 表示每行允许的字符数为 120。这个数字是经过开发者们商定的。

  • 该路径可以指向多个文件, 可以一个接一个, 也可以像典型的unixshell一样使用通配符.

预提交钩子

为了便于使用，我们提供了基于 pre-commit Python 框架的 Git 钩子，可以对你的所有提交自动运行 ruff，同时确保使用的是正确版本的 ruff。设置方法是这样的：

  1. pip install pre-commit
  2. pre-commit install

你还可以使用 pre-commit run 手动运行这个钩子。

备注

Previously, we supplied a hook in the folder misc/hooks. If you copied the script manually, these hooks should still work, but symlinks will be broken. If you are using the new system, run rm .git/hooks/* to remove the old hooks that are no longer needed.

编辑器集成

Many IDEs or code editors have beautifier plugins that can be configured to run ruff automatically, for example, each time you save a file. For details, you can check Ruff Integrations.

注释风格指南

本注释风格指南适用于Godot代码库中使用的所有编程语言.

  • 以空间字符开始注释, 以将其与禁用代码区分开来.

  • 注释使用句子大小写. 注释以大写字母开头, 并始终以句号结束.

  • 使用反引号引用变量和函数名和值.

  • 将注释控制在~100个字符。

  • You can use TODO:, FIXME:, NOTE:, or HACK: as admonitions when needed.

示例:

  1. // Compute the first 10,000 decimals of Pi.
  2. // FIXME: Don't crash when computing the 1,337th decimal due to `increment`
  3. //        being negative.

不要在注释中重复代码的内容. 解释 为什么 而不是 如何 .

错误做法：

  1. // Draw loading screen.
  2. draw_load_screen();

你可以在函数或宏定义上面使用Javadoc风格的注释. 建议只对不公开给脚本的方法使用Javadoc风格的注释. 这是因为公开的方法应该在 class reference XML 中进行记录.

示例:

  1. /**
  2.  * Returns the number of nodes in the universe.
  3.  * This can potentially be a very large number, hence the 64-bit return type.
  4.  */
  5. uint64_t Universe::get_node_count() {
  6.     // ...
  7. }

对于成员变量, 不要使用Javadoc式的注释, 而是使用单行注释:

  1. class Universe {
  2.     // The cached number of nodes in the universe.
  3.     // This value may not always be up-to-date with the current number of nodes
  4.     // in the universe.
  5.     uint64_t node_count_cached = 0;
  6. };