Up to date

This page is up to date for Godot 4.2. If you still find outdated information, please open an issue.

Writing guidelines

Godotコミュニティは豊かで国際的です。ユーザーは世界中から来ています。若い人もいれば、英語を母国語としない人もいます。だからこそ、私たちは皆、明確で共通の言語を使って書かなければならないのです。クラス参照の場合、目標は、すべての人にとって読みやすく、正確に読みやすくすることです。

要約すると、常に次のように努めます:

  1. Use the active voice

  2. 正確なアクション動詞を使用する

  3. 「-ing」で終わる動詞は避けてください

  4. 不要な副詞や形容詞を削除します。

  5. これらの8つの単語を禁止: 明白な、シンプル、基本的な、簡単、実際、ちょうど、明確、および

  6. 明示的な参照を使用する

  7. 「's」を使用して所有物を表示する

  8. オックスフォードコンマを使用する

クラスを記述する3つのルールがあります:

  1. 簡単な説明でノードの概要を説明する

  2. 役に立つ場合に返すメソッドについて言及する

  3. 「if true」を使用してブール値を記述する

注釈

テクニカルライターの仕事は、可能な限り多くの情報を可能な限り小さく、最も明確な文章に詰め込むことです。これらのガイドラインは、その目標に向かって取り組むのに役立ちます。

参考

See the content guidelines for information on the types of documentation you can write in the official documentation.

明確な英語のためのルール７つ

Use the active voice

Use the active voice when possible. Take the classes, methods, and constants you describe as the subject. It's natural to write using the passive voice, but it's harder to read and produces longer sentences.

受動態:

The man **was bitten** by the dog.

能動態:

The dog bit the man.

受動態を使用しないでください :

void edit_set_pivot ( Vector2 pivot )
[...] This method **is implemented** only in some nodes that inherit Node2D.

ノードの名前を名詞として使用してください:

void edit_set_pivot ( Vector2 pivot )
[...] Only some Node2Ds **implement** this method.

正確なアクション動詞を使用する

make や set などの一般的な動詞や、1 つの単語で置き換えることができる式よりも、正確で一般的な動詞を優先します。

メソッドの名前を繰り返さないで下さい。ピボット値を新しいピボット値に設定済みと指定しています:

void edit_set_pivot ( Vector2 pivot )
Set the pivot position of the 2D node to [code]pivot[/code] value. [...]

この「セット」の結果について説明してください。 place 、 position 、 rotate 、 fade などの正確な動詞を使用します。

void edit_set_pivot ( Vector2 pivot )
Position the node's pivot to the [code]pivot[/code] value. [...]

「-ing」で終わる動詞は避けてください

進行形は、連続的なアクションを記述します。例えば「呼び出し中」、「移動中」などです。

すぐにされる変更には進行形を使用しないでください。

Vector2 move ( Vector2 rel_vec )
Move the body in the given direction, **stopping** if there is an obstacle. [...]

Do use simple present, past, or future.

Vector2 move ( Vector2 rel_vec )
Moves the body in the vector's direction. The body **stops** if it collides with an obstacle. [...]

Exception: If the subject is not clear, replacing "ing" verbs is not an improvement. For example, in the previous sentence, "it replaces" would not make much sense where "replacing" currently is.

進行時制を使用して、時間的に連続するアクションを記述することができます。 アニメーションやコルーチンなど。

ちなみに

動詞は-ingで形容詞的名詞になります。これは活用ではないので、 the remaining movement 、 the missing file などのように使用できます。

不要な副詞や形容詞を削除する

形容詞や副詞をできるだけ少なく書いてください。説明に重要な情報を追加する場合にのみ使用してください。

冗長または無意味な副詞を使用しないでください。ドキュメントを長くするが、情報を追加しない単語:

**Basically** a big texture [...]

簡単で説明的な言語で短い文章を書いて下さい:

A big texture [...]

これらの8つの単語を禁止

これらの8つの禁止単語を使用しないでください:

  1. 明らかな

  2. シンプルな

  3. 基本的な

  4. 簡単な

  5. 実際の

  6. ちょうどの

  7. はっきりとした

  8. しかし(一部の用途)

ゲームの作成とプログラミングは簡単ではありませんし、初めてAPIを使用することを学ぶ人にとって簡単なことではありません。リスト内の他の単語 ( just や actual など)は、文章に情報を追加しません。対応する副詞も使用しないでください:明らかに、基本的に、簡単に、実際には、はっきりと。

例を挙げないでください。 禁止された言葉は説明を長くし、最も重要な情報から注意をそらします:

**TextureRect**
Control frame that **simply** draws an assigned texture. It can stretch or not. It's a **simple** way to **just** show an image in a UI.

それらを削除します:

**TextureRect**
[Control] node that displays a texture. The texture can stretch to the node's bounding box or stay in the center. Useful to display sprites in your UIs.

「シンプル」は決して役に立ちません。 他のユーザーにとっては、複雑なものやイライラするものがあります。 古き良き時代のようなものはありません。 古い簡単な説明は、タイマーノードのページの最初の文です:

**Timer**
A **simple** Timer node.

ノードが代わりに何を行うかを説明してください:

**Timer**
Calls a function of your choice after a certain duration.

「基本」を使用しないでください、それはあまりにもあいまいです:

**Vector3**
Vector class, which performs **basic** 3D vector math operations.

簡単な説明を使用して、ノードの概要を説明してください:

**Vector3**
Provides essential math functions to manipulate 3D vectors: cross product, normalize, rotate, etc.

明示的な参照を使用する

暗黙的な参照よりも明示的な参照を優先します。

「前者」、「後者」などの言葉を使用しないでください。これらは英語では最も一般的ではなく、リファレンスを確認する必要があります。

[code]w[/code] and [code]h[/code] define right and bottom margins. The **latter** two resize the texture so it fits in the defined margin.

言葉を繰り返してください。 それらはすべての曖昧さを取り除きます:

[code]w[/code] and [code]h[/code] define right and bottom margins. **[code]w[/code] and [code]h[/code]** resize the texture so it fits the margin.

同じ変数名を3回または4回繰り返す必要がある場合は、説明を書き換える必要があります。

「's」を使用して所有物を表示する

「The milk of the cow」を避けてください。 英語では不自然に感じます。 代わりに「The cow's milk」と書いてください。

「of the X」とは書かないでください:

The region **of the AtlasTexture that is** used.

所有格の 's を使用してください。文の先頭に主語を置き、短くすることができます:

The **AtlasTexture's** used region.

オックスフォードコンマを使用して何かを列挙する

オックスフォード辞書から:

「オックスフォードコンマ」は、リストの最後にある「and」という語の前にあるオプションのコンマです。書籍、ビデオ、雑誌を販売しています。

[...] 全ての作家や出版社が使っているわけではありませんが、リストの中の項目が単一の単語ではない場合、文章の意味を明確にすることができます:これらの項目は白黒、赤と黄色、青と緑で利用できます。

コンマなしでリストの最後の要素を残さないでください:

Create a CharacterBody2D node, a CollisionShape2D node and a sprite node.

2つ以上の要素を持つリストの最後の要素に and または or の前にコンマを追加してください。

Create a CharacterBody2D node, a CollisionShape2D node, and a sprite node.

メソッドとクラスの記述方法

動的な型指定と静的な型指定

ドキュメントのコード例は、ユーザーを混乱させないために一貫したスタイルに従う必要があります。静的型ヒントはGDScriptのオプション機能であるため、動的コードの記述に固執することにしました。これにより、簡潔でアクセス可能なGDScriptを作成できます。

例外は、静的型付けの概念をユーザーに説明するトピックです。

型ヒントを、コロンで追加したりキャストしたりしないでください:

const MainAttack := preload("res://fire_attack.gd")
var hit_points := 5
var name: String = "Bob"
var body_sprite := $Sprite2D as Sprite2D

Do write constants and variables with dynamic typing:

const MainAttack = preload("res://fire_attack.gd")
var hit_points = 5
var name = "Bob"
var body_sprite = $Sprite2D

推論された引数または戻り値の型を持つ関数を記述しないでください:

func choose(arguments: PackedStringArray) -> String:
    # Chooses one of the arguments from array with equal chances
    randomize()
    var size := arguments.size()
    var choice: int = randi() % size
    return arguments[choice]

動的型付けを使用して関数を作成する:

func choose(arguments):
    # Chooses one of the arguments from array with equal chances
    randomize()
    var size = arguments.size()
    var choice = randi() % size
    return arguments[choice]

必要に応じて、実際のコード例を使用します

実世界の例は、抽象的な foos および bars よりも初心者にとってアクセスしやすいです。また、ゲームプロジェクトから直接コピーして、コードスニペットがエラーなしでコンパイルされるようにすることもできます。

var my_var = 10 ではなく var speed = 10 と書くと、初心者はコードをよりよく理解できます。ライブプロジェクトでコードスニペットを使用できる場所に関する参照フレームを提供します。

作成例を書かないでください:

@onready var a = preload("res://MyPath")
@onready var my_node = $MyNode


func foo():
    # Do stuff

具体的な例を書きます:

@onready var sfx_player_gun = preload("res://Assets/Sound/SFXPlayerGun.ogg")
@onready var audio_player = $Audio/AudioStreamPlayer


func play_shooting_sound():
    audio_player.stream = sfx_player_gun
    audio_player.play()

もちろん、実際の例を使用するのは実用的でない場合があります。これらの状況では、my_var、foo() ``\ 、または ``my_func() などの名前の使用を避け、例にとってより意味のある名前を検討する必要があります。

簡単な説明でノードの概要を説明する

簡単な説明は、参照の最も重要な文です。これは、ユーザーがノードと最初に接触した場合です:

  1. これは、「新しいノードを作成」ダイアログボックスの唯一の説明です。

  2. 参照内のすべてのページの一番上に表示されます

簡単な説明では、ノードの役割とその機能を最大200文字で説明する必要があります。

小さくてあいまいな要約を書かないで下さい:

**Node2D**
Base node for 2D system.

ノードの機能の概要を説明してください:

**Node2D**
A 2D game object, inherited by all 2D-related nodes. Has a position, rotation, scale, and Z index.

ノードの完全な説明を使用して、詳細情報とコード例を提供します(可能であれば)。

役に立つ場合に返すメソッドについて言及する

重要な値を返すメソッドもあります。説明の最後に、理想的には新しい行でそれらを説明します。名前が set または get で始まるメソッドの戻り値を言及する必要はありません。

受動態を使用しないでください :

Vector2 move ( Vector2 rel_vec )
[...] The returned vector is how much movement was remaining before being stopped.

常に「Returns」を使用してください。

Vector2 move ( Vector2 rel_vec )
[...] Returns the remaining movement before the body was stopped.

「能動態」ルールの例外に注意してください: moveメソッドを使用すると、外部コライダがメソッドと move を呼び出す本文に影響を与える可能性があります。この場合、受動態を使用できます。

「if true」を使用してブール値を記述する

ブールメンバ変数の場合は、常に `` if true`` および/または `` if false`` を使用して明示的にしてください。 「コントロールするかどうか」はあいまいである可能性があり、すべてのメンバー変数に対して機能しません。

Also, surround boolean values, variable names and methods with [code][/code].

"if true" から始めてください:

Timer.autostart
If [code]true[/code], the timer will automatically start when entering the scene tree.

引数の周りに [code] を使用する

クラス参照では、引数を常に [code][/code] で囲みます。ドキュメントとGodotでは、このよう に表示されます。 GodotリポジトリでXMLファイルを編集するときは、'this' や `this` などの既存の引数を [code]this[/code] に置き換えます。

Godotのドキュメントで使用する一般的な語彙

開発者は、インターフェイスの領域を指す特定の単語を選択しました。 それらはソースやドキュメントで使用されており、同義語の代わりに常に使用する必要があります。そうすれば、ユーザーはあなたが何を話しているのかを知ることができます。

インターフェイスと一般的な語彙の概要

インターフェイスと一般的な語彙の概要

エディタの左上隅に main menus があります。中央のボタンで workspace が変更されます。そして、右上のボタンは playtest buttons です。2Dまたは3D空間を表示する中央の領域は viewport です。上部には、 toolbar 内の tools のリストがあります。

ビューポートの両側のタブまたはドッキング可能なパネルは docks です。 FileSystem dock 、シーンツリーを含む Scene dock 、 Import dock 、 Node dock 、 Inspector または Inspector dock があります。 デフォルトのレイアウトでは、タブ付きドックを tabs と呼ぶことができます: Scene tab 、 Node tab ...

ビューポートの下部にあるアニメーション、デバッガなどは panels``です。彼らは一緒に ``bottom panels を構成します。

Foldable areas of the Inspector are sections. The node's parent class names, which you can't fold, are Classes e.g. the CharacterBody2D class. And individual lines with key-value pairs are properties. E.g. position or modulate color are both properties.

キーボードショートカットのガイドライン

キーボードとマウスのショートカットは :kbd: タグを使用する必要があります。これにより、ショートカットを残りのテキストやインラインコードから際立たせることができます。修飾キー(Ctrl/Cmd)のスペルチェックされた形式(Control/Command)ではなく、コンパクトキーを使用します。組み合わせの場合は、シンボルの両側にスペースがある + シンボルを使用します。

他のプラットフォームと比較してmacOSでは異なるショートカットを必ず記載してください。macOSでは、キーボードショートカットの Ctrl が Cmd に置き換えられることがよくあります。

ショートカットを可能な限り文章に組み込むようにしてください。わかりやすくするために :kbd: タグをそのまま残した例をいくつか示します:

  • :kbd:`Ctrl + Alt + T` を押してパネルを切り替えます(macOSでは :kbd:`Cmd + Alt + T`)。

  • :kbd:`Space` を押し、マウスの左ボタンを押したままにして2Dエディタでパンします。

  • :kbd:`Shift + 上矢印` を押して、ノードを8ピクセル上に移動します。