コードスタイルガイドライン¶

Godotのソースコードに投稿する場合は、以下に示すスタイルガイドラインに従ってください。一部のインテグレーションプロセスを介してチェックされ、レビュー担当者から潜在的な問題の修正を求める質問が表示されますので、以下に示すようにシステムをセットアップして、すべてのコミットがガイドラインに従うようにします。

C++およびObjective-C¶

文書化されたガイドラインはありませんが、開発者によって合意されたコードスタイルは、clang形式のコードビューティファイヤを介して適用されます。いくつか例を挙げると:

インデントと配置は両方ともタブベースです(それぞれ1つと2つのタブ)
コンマの後だけでなく、数学演算子と代入演算子の周りに1つのスペース
ポインタ演算子と参照演算子は、型名ではなく変数識別子に貼り付けられます
ヘッダーのインクルードに関する詳細を参照してください

clang形式で使用されるルールは、Godotリポジトリの.clang形式ファイルで概説されています。

スタイルが周囲のコードと一致し、末尾の空白やスペースベースのインデントを導入しない限り、問題ありません。ただし、定期的に投稿する場合は、すべてのコミットをチェックして自動的に修正するために、clang形式をローカルに設定することを強くお勧めします。

警告

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 come 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.

Third-party code is usually included in the thirdparty/ folder and can thus easily be excluded from formatting scripts. For the rare cases where a third-party code snippet needs to be included directly within a Godot file, you can use /* clang-format off */ and /* clang-format on */ to tell clang-format to ignore a chunk of code.

参考

These guidelines only cover code formatting. See C++ usage guidelines for a list of language features that are permitted in pull requests.

clang形式をローカルで使用する¶

First of all, you will need to install clang-format. As of now, you need to use clang-format 13 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.

インストール手順¶

clang形式をインストールする方法は次のとおりです:

Linux: 通常、ディストリビューションによってパッケージ化されたclangツールチェーンですぐに使用できます。ディストリビューションのバージョンが必要なバージョンではない場合、コンパイル済みのバージョンを `LLVMウェブサイト<http://releases.llvm.org/download.html>`__からダウンロードできます。または、Debian派生物を使用している場合は、`upstream repos <http://apt.llvm.org/>`__を使用します。
macOSおよびWindows: プリコンパイルされたバイナリは、 LLVM Webサイト<http://releases.llvm.org/download.html>`__からダウンロードできます。バイナリのフォルダへのパスをシステムの ``PATH` 環境変数に追加して、clang-format をすぐに呼び出せるようにする必要があります。

変更にclang-formatを適用する方法はいくつかあります:

手動使用¶

次のコマンドを使用して、clang形式の1つ以上のファイルを手動で適用できます:

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

-i は、変更をファイルに直接書き込む必要があることを意味します(デフォルトではclang形式では、固定バージョンは端末にのみ出力されます)。
パスは、次々に、または典型的なUnixシェルのようにワイルドカードを使用して、複数のファイルを指すことができます。グロブするときは、Godotのツリーにあるコンパイル済みオブジェクト(.oおよび.aファイル)でclang-formatを実行しないように注意してください。そのため、 core/* よりも core/*.{cpp,h} を使用する方が適切です。

プレコミットフック¶

使いやすさのために、Gitのプレコミットフックを提供し、すべてのコミットで自動的にclang形式を実行してチェックし、最終的なコミットでその変更を適用できるようにします。

この「フック」は misc/hooks で見つけることができるスクリプトであり、インストール手順については、そのフォルダのREADME.mdを参照してください。

あなたのclang-formatが `` PATH`` にない場合、動作するために正しいバイナリを指すように pre-commit-clang-format を編集する必要があるかもしれません。このフックはLinuxおよびmacOSでテストされましたが、WindowsのGitシェルでも動作するはずです。

IDEプラグイン¶

ほとんどのIDEまたはコードエディタには、ファイルを保存するたびに、clang形式を自動的に実行するように構成できる美しいプラグインがあります。

一部のIDE用の美しいプラグインの非網羅的なリストを以下に示します:

Qtクリエイター:ビューティフィア・プラグイン
Visual Studio Code: Clang-Format
Visual Studio: ClangFormat
vim: vim-clang-format
CLion: Starting from version 2019.1, no plugin is required. Instead, enable ClangFormat

(プルリクエストは、テストされたプラグインでこのリストを拡張することを歓迎します。)

ヘッダーのインクルード¶

新しいC++またはObjective-Cファイルを追加するとき、または既存のファイルに新しいヘッダーを含めるときは、次の規則に従う必要があります:

ファイルの最初の行は、別のファイルからコピーアンドペーストされたGodotの著作権ヘッダーとMITライセンスでなければなりません。必ずファイル名を調整してください。
.h ヘッダーでは、インクルードガードを FILENAME_H の形式で使用する必要があります。
.cpp ファイル(たとえば filename.cpp)では、最初のインクルードはクラスが宣言されているもの(たとえば #include "filename.h")で、その後に分離のための空白行が続く必要があります。
次に、Godot独自のコードベースからヘッダーを取得します。このヘッダーは、アルファベット順(clang-format で強制)に含まれ、ルートフォルダからの相対パスを持ちます。これらのインクルードは引用符で行う必要があります。#include "core/object.h"。 Godotヘッダーのインクルードブロックの後には、分離のために空白行が続く必要があります。
Finally, third-party headers (either from thirdparty or from the system's include paths) come next and should be included with the < and > symbols, e.g. #include <png.h>. The block of third-party headers should also be followed by an empty line for separation.
Godot and third-party headers should be included in the file that requires them, i.e. in the .h header if used in the declarative code or in the .cpp if used only in the imperative code.

例:

/*************************************************************************/
/*  my_new_file.h                                                        */
/*************************************************************************/
/*                       This file is part of:                           */
/*                           GODOT ENGINE                                */
/*                      https://godotengine.org                          */
/*************************************************************************/
/* Copyright (c) 2007-2021 Juan Linietsky, Ariel Manzur.                 */
/* Copyright (c) 2014-2021 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-2021 Juan Linietsky, Ariel Manzur.                 */
/* Copyright (c) 2014-2021 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's Java code (mostly in platform/android) is also enforced via clang-format, so see the instructions above to set it up. Keep in mind that this style guide only applies to code written and maintained by Godot, not third-party code such as the java/src/com/google subfolder.

Python¶

GodotのSConsビルドシステムはPythonで書かれており、ソースツリーに含まれる様々なスクリプトもPythonを使用しています。

For those, we follow the Black style guide. Blacken your Python changes using Black.

Using black locally¶

First of all, you will need to install black. Black requires Python 3.6.0+ to run.

インストール手順¶

Here's how to install black:

pip3 install black --user

You then have different possibilities to apply black to your changes:

手動使用¶

You can apply black manually to one or more files with the following command:

black -l 120 <path/to/file(s)>

-l 120 means that the allowed number of characters per line is 120. This number was agreed upon by the developers.
The path can point to several files, either one after the other or using wildcards like in a typical Unix shell.

プレコミットフック¶

For ease of use, we provide a pre-commit hook for Git that will run black automatically on all your commits to check them, and let you apply its changes in the final commit.

This "hook" is a script which can be found in misc/hooks. Refer to that folder's README.md for installation instructions.

Editor integration¶

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

Comment style guide¶

This comment style guide applies to all programming languages used within Godot's codebase.

Begin comments with a space character to distinguish them from disabled code.
Use sentence case for comments. Begin comments with an uppercase character and always end them with a period.
Reference variable/function names and values using backticks.
Wrap comments to ~100 characters.
You can use TODO:, FIXME:, NOTE:, or HACK: as adominitions when needed.

例:

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

Don't repeat what the code says in a comment. Explain the why rather than how.

Bad:

// Draw loading screen.
draw_load_screen();

You can use Javadoc-style comments above function or macro definitions. It's recommended to use Javadoc-style comments only for methods which are not exposed to scripting. This is because exposed methods should be documented in the class reference XML instead.

例:

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

For member variables, don't use Javadoc-style comments but use single-line comments instead:

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

コードスタイルガイドライン¶

C++およびObjective-C¶

clang形式をローカルで使用する¶

インストール手順¶

手動使用¶

プレコミット フック¶

IDEプラグイン¶

ヘッダーのインクルード¶

Java¶

Python¶

Using black locally¶

インストール手順¶

手動使用¶

プレコミット フック¶

Editor integration¶

Comment style guide¶

プレコミットフック¶

プレコミットフック¶