Up to date

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

說明文件撰寫方針

Godot 的社群很多元且國際化。有許多來自世界各處的使用者。其中，有些使用者很年輕，而很多使用者也並非英語母語者。這就是我們應使用清晰明瞭且通用語言的原因。對於類別參照文件，撰寫目標應為讓所有人都能輕鬆閱讀且內容準確。

總之，請儘量：

  1. 使用直觀的語調

  2. 使用精準的動作動詞

  3. 避免以 -ing 結尾的動詞

  4. 移除不必要的副詞與形容詞。

  5. 不得使用這 8 個單詞：obvious, simple, basic, easy, actual, just, clear 與 however

  6. 使用明顯引用

  7. 使用「's」來標示擁有關係

  8. 使用牛津逗號 (Oxford comma)

下列 3 個規則用於描述類別：

  1. 以簡單扼要的描述說明節點

  2. 若方法的回傳值有功能的話，應提及其回傳值

  3. 使用「if true」來描述布林值

備註

技術性作家的工作就是儘量將多個資訊以最少且最清晰的句子提供。這些方針有助於讓你達到此一目標。

也參考

請查看:ref:內容規範 <doc_content_guidelines>，瞭解你可以在官方文件中編寫哪些型別的文件。

讓英語清晰明瞭的 7 個規則

使用直觀的語調

儘量使用直觀的語調。以要說明的類別、方法與常數作為句子的主詞。雖然使用被動語態來撰寫比較自然，但這樣也讓句子難以閱讀且讓句子變長。

被動句：

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 等動詞以及任何可以用單一單詞替換的句子。

不要 重複方法的名稱。方法名稱已經說了是將樞紐值設為新值 (Set the pivot value to a new one)：

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

說明 這裡「set」這個詞造成的結果是什麼：使用如 place, position, rotate, fate…等的精準描述的動詞。

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

避免以 -ing 結尾的動詞

進行式是用來描述持續動作的，如「is calling (正在呼叫)」、「is moving (正在移動)」。

不要 在發生立即性改動時使用進行式。

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

使用 簡單的現在、過去、或未來式。

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

例外：當主詞不清楚時，就沒辦法通過換掉「ing」動詞來讓句子更清楚。舉例來說，前一句話的原文「If the subject is not clear, replacing "ing" verbs is not an improvement.」裡，用「is replaces」取代「replacing」並沒有讓句子比較好讀。

要描述隨著時間持續發生的動作時，可以使用進行式。如動畫或協同程式 (Coroutine)。

小訣竅

動詞可以通過加上 -ing 來轉成形容詞。這種做法並不是時態變化，所以這種情況可以加上 -ing：the remaining movement, the missing file…等。

移除不必要的副詞與形容詞

儘量少寫一點副詞與形容詞。只有當這些副詞與形容詞對於目前描述的內容提供了足夠關鍵的資訊才能使用。

不要 使用不必要或無意義的副詞。這些單詞會讓說明文件變長，而並沒有加上太多資訊：

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

使用 較短的句子，以簡單、描述性的話語來撰寫：

A big texture [...]

禁止使用這 8 個單詞

不準 使用這 8 個禁用詞：

  1. obvious

  2. simple

  3. basic

  4. easy

  5. actual

  6. just

  7. clear

  8. however (某些情況)

創造遊戲與程式設計並不簡單，而對於初次學習使用 API 的人來說也是如此。列表上的其他單詞，如 just 與 actial 等並沒有給句子加上其他意思。也不要使用這些單詞對應的副詞：obviously, simply, basically, easily, actually, clearly。

錯誤 範例。這些禁用詞會讓描述句子變得更長，且會讓注意力無法集中在最重要的資訊上：

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

用「Simple」根本沒用。請記得，對於其他使用者來說，任何東西都可能很複雜且讓使用者挫敗。沒有比 is't simple (這很簡單) 還能讓你更挫折的了。下列為以前在 Timer 節點頁上簡介的第一句話：

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

應 解釋該節點做了什麼：

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

不要 使用「Basic」，太模糊了：

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

使用 描述該節點的簡要說明：

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

使用明顯引用

優先使用明顯參照而非隱含參照。

不要 使用如「the former (前者)」、「the latter (後者)」等詞。這些字在英語中並不常見，在閱讀上會需要參考是在引述什麼。

[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」前可選的逗號： We sell books, videos, and magazines.

[...] 並非所有作家與出版社都使用牛津逗號，但使用牛津逗號可以在當列表內的專案並非完整單詞時說清楚句子的意思： These items are available in black and white, red and yellow, and blue and green.

不要 忘記在列表中最後一個元素前加上逗號：

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

應 在當列表有超過兩個元素時，在最後一個元素的 and 或 or 之前加上逗號。

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

如何撰寫方法與類別

動態 v.s. 靜態型別

說明文件中的程式碼範例應該要遵從一貫的風格，以免造成使用者混淆。由於靜態型別是 GDScript 可選的功能，因此我們可以選擇固定撰寫動態程式碼。這樣也可以讓我們寫出簡潔且存取性更好的 GDScript 程式碼。

向使用者說明靜態型別的主題時為此規則的例外。

不要 使用分號或型別轉換來加上型別提示：

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

使用 靜態型別來撰寫常數與變數：

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]

在適當的時候使用真實案例

真實案例對於使用者來說比起抽象的 foo 與 bar 來說更好理解。也可以直接從你的遊戲專案裡直接複製貼上範例程式碼，並請確保這些程式碼片段在編譯的時候不會出現問題。

使用 var speed = 10 而不是 var my_var = 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.

請注意「直接語調」的例外規則：with the move method, an external collider can influence the method and the body that calls move. 在這個例子中，可以使用被動語態。

使用「if true」來描述布林值

對於布林成員變數，應使用 if true 與／或 if false 來明確表達。Controls whether or not 這樣的句子可能不夠明確，且並非所有成員變數都適用。

另外，請以 [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 說明文件中常用的詞彙

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 (節點分頁) ...

動畫、除錯工具…等放在檢視區下方的是 Panel (面板) 。這些面板組合在一起稱為 Bottom Panel (底部面板) 。

屬性面板中可摺疊的區域為 Sections (段落) 。可摺疊的母節點名稱為 Classes (類別) ，如 KinematicBody2D 類別 。每行獨立的索引鍵／值組為 Properties (屬性) 。如 positon 或 modulate color 都是 Properties (屬性) 。

鍵盤快捷鍵方針

鍵盤與滑鼠快捷鍵應使用 :kbd: 標籤，使用該標籤可以區分出快捷鍵與其他文字、行內程式碼的不同。請使用簡寫形式的按鍵名稱 (Ctrl / Cmd) 而不要寫出全名 (Control / Command) 。組合快捷鍵請使用 + 符號，並在該符號左右兩次加上空格。

請確保當快捷鍵在 macOS 上不同時應特別提及。在 macOS 上的鍵盤快捷鍵通常使用 Cmd 來取代 Ctrl 。

請儘量將快捷鍵整合到句子裡。下列為一些將 :kbd: 標籤直接放在句子裡提升可見性的例子：

  • 按 :kbd:`Ctrl + Alt + T` 來開啟或關閉面板 (macOS 上為 :kbd:`Cmd + Alt + T`)。

  • 按 :kbd:`空白鍵` 並按住滑鼠左鍵以平移 2D 編輯器。

  • 按 :kbd:`Shift + 上方向鍵` 來將節點向上移動 8 像素。