代码样式准则

在为Godot的源代码做贡献时,您需要遵循下面概述的样式指南。其中一些是通过持续集成过程进行检查的,审阅者将要求您修复潜在问题,因此,最好按照下面概述的方式设置您的系统,以确保所有提交都遵循指导原则。

C++与ObjuleC

没有书面的指导原则,但是开发人员同意的代码样式是通过 clang-format 代码美化器,它照顾你的所有公约。举几个例子:

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

  • 一个围绕数学和作业运算符以及逗号的空格

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

  • 有关收割台包括,请参阅下文。

Clang格式使用的规则在 .clang-format Godot存储库的文件。

只要确保样式与周围的代码匹配,并且不引入尾随空格或基于空格的缩进,就可以了。但是,如果您计划定期提交,我们强烈建议您在本地设置clang格式,以检查并自动修复所有提交。

警告

Godot的代码风格应该 not 应用于第三方代码,即包含在Godot的源代码树中,但不是专门为我们的项目编写的代码。这些代码通常来自不同的上游项目,它们有自己的风格指南(或者缺乏风格指南),并且不想引入差异,这会使与上游存储库的同步更加困难。

第三方代码通常包含在 thirdparty/ 文件夹,因此很容易从格式化脚本中排除。对于需要将第三方代码片段直接包含在godot文件中的罕见情况,可以使用 /* clang-format off *//* clang-format on */ 告诉clang格式忽略一段代码。

本地使用clang格式

首先,您需要安装clang格式。从现在起,你需要使用 clang-format 8.x 与Godot的格式兼容。更高的版本可能是合适的,但是以前的版本有错误,会导致当前代码库的格式更改。

安装

以下是安装clang格式的方法:

  • Linux:它通常可以随发行版打包的clang工具链一起开箱即用。如果您的发行版不是必需的版本,您可以从 LLVM website 或者,如果您使用的是Debian衍生工具,请使用 upstream repos .

  • MacOS和Windows:您可以从 LLVM website . 您可能需要将二进制文件文件夹的路径添加到系统的 PATH 能够调用的环境变量 clang-format 开箱即用。

然后,您可以将clang格式应用于更改:

手动使用

可以使用以下命令手动应用clang格式的一个或多个文件:

clang-format -i <path/to/file(s)>
  • -i 意味着更改应该直接写入文件(默认情况下,clang格式只将固定版本输出到终端)。

  • 路径可以指向多个文件,可以是一个接一个,也可以像在典型的Unix shell中那样使用通配符。在全局设置时要小心,这样就不会在Godot树中的已编译对象(.o和.a文件)上运行clang格式。所以更好的使用 core/*.{{cpp,h}}core/* .

预提交挂钩

为了便于使用,我们为Git提供了一个预提交钩子,它将在所有提交上自动运行clang格式以检查它们,并允许您在最终提交中应用其更改。

这个“钩子”是一个脚本,可以在 misc/hooks ,有关安装说明,请参阅该文件夹的readme.md。

如果您的Clang格式不在 PATH ,您可能需要编辑 pre-commit-clang-format 指向正确的二进制文件。钩子在Linux和MacOS上进行了测试,但也可以在Windows上的Git shell中使用。

IDE插件

大多数IDE或代码编辑器都有美化插件,可以配置为自动运行clang格式,例如每次保存文件时。

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

(Pull请求欢迎使用测试插件扩展此列表。)

收割台包括

当在现有的文件中添加新的C++或Objy-C文件或包含新的头文件时,应遵循以下规则:

  • 文件中的第一行应该是Godot的版权标题和MIT许可证,从另一个文件粘贴副本。请确保调整文件名。

  • 在一个 .h 表头,包括护板应与表单一起使用 FILENAME_H .

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

  • 然后来自Godot自己的代码库的头,按字母顺序包含(由 clang-format )与根文件夹相关的路径。这些包括应该用引号来完成,例如 #include "core/object.h" . 然后,godot header include块后面应该有一个空行用于分隔。

  • 最后,第三方标题(来自 thirdparty 或者从系统的include路径)进入下一个,并且应该包含在<和>符号中,例如 #include <png.h> . 第三方头段的块后面也应该有一个空行,用于分隔。

  • godot和thirdparty头应包含在需要它们的文件中,即 .h 如果在声明性代码或 .cpp 如果仅在命令代码中使用。

例子:

/*************************************************************************/
/*  my_new_file.h                                                        */
/*************************************************************************/
/*                       This file is part of:                           */
/*                           GODOT ENGINE                                */
/*                      https://godotengine.org                          */
/*************************************************************************/
/* Copyright (c) 2007-2019 Juan Linietsky, Ariel Manzur.                 */
/* Copyright (c) 2014-2019 Godot Engine contributors (cf. AUTHORS.md)    */
/*                                                                       */
/* Permission is hereby granted, free of charge, to any person obtaining */
/* a copy of this software and associated documentation files (the       */
/* "Software"), to deal in the Software without restriction, including   */
/* without limitation the rights to use, copy, modify, merge, publish,   */
/* distribute, sublicense, and/or sell copies of the Software, and to    */
/* permit persons to whom the Software is furnished to do so, subject to */
/* the following conditions:                                             */
/*                                                                       */
/* The above copyright notice and this permission notice shall be        */
/* included in all copies or substantial portions of the Software.       */
/*                                                                       */
/* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,       */
/* EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF    */
/* MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.*/
/* IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY  */
/* CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,  */
/* TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE     */
/* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.                */
/*************************************************************************/

#ifndef MY_NEW_FILE_H
#define MY_NEW_FILE_H

#include "core/hash_map.h"
#include "core/list.h"
#include "scene/gui/control.h

#include <png.h>

...

#endif // MY_NEW_FILE_H
/*************************************************************************/
/*  my_new_file.cpp                                                      */
/*************************************************************************/
/*                       This file is part of:                           */
/*                           GODOT ENGINE                                */
/*                      https://godotengine.org                          */
/*************************************************************************/
/* Copyright (c) 2007-2019 Juan Linietsky, Ariel Manzur.                 */
/* Copyright (c) 2014-2019 Godot Engine contributors (cf. AUTHORS.md)    */
/*                                                                       */
/* Permission is hereby granted, free of charge, to any person obtaining */
/* a copy of this software and associated documentation files (the       */
/* "Software"), to deal in the Software without restriction, including   */
/* without limitation the rights to use, copy, modify, merge, publish,   */
/* distribute, sublicense, and/or sell copies of the Software, and to    */
/* permit persons to whom the Software is furnished to do so, subject to */
/* the following conditions:                                             */
/*                                                                       */
/* The above copyright notice and this permission notice shall be        */
/* included in all copies or substantial portions of the Software.       */
/*                                                                       */
/* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,       */
/* EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF    */
/* MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.*/
/* IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY  */
/* CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,  */
/* TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE     */
/* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.                */
/*************************************************************************/

#include "my_new_file.h"

#include "core/math/math_funcs.h"
#include "scene/gui/line_edit.h

#include <zlib.h>
#include <zstd.h>

Java

Godot的Java代码(主要在 platform/android )也通过强制执行 clang-format ,请参阅上面的设置说明。请记住,此样式指南仅适用于Godot编写和维护的代码,而不是第三方代码,如 java/src/com/google 子文件夹。

Python

Godot的scons构建系统是用python编写的,源代码树中包含的各种脚本也在使用python。

对于那些,我们遵循 PEP-8 style guide 但是,这并不像C++代码那样强制执行。如果您愿意,可以使用 autopep8 .