Up to date

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

程式碼樣式方針

本文件致力於説明大家評估哪些內容應該加入到官方文件中。你可以在下面找到一些關於如何編寫簡單易懂的內容的原則和建議。

我們想實作兩個目標：

  1. **與使用者共情。**寫作時，應該讓通過文件來學習變得簡單。

  2. 編寫完善的參考手冊。我們這裡的目標不是教授程式設計的基礎知識。我們應該提供瞭解如何使用 Godot 功能的參考材料。

規範與原則

以下是我們應該努力遵守的規範。不過這些並不是硬性規定：特殊情況下，某個主題會需要打破這裡的若干規範。不過我們還是應該儘量完成上面所列出的兩個目標。

撰寫自定說明文件

功能在編寫文件前是不存在的。如果使用者無法找到某個功能的資訊和用法，那麼這個功能對於他們就不存在。我們應該保證涉及到 Godot 的方方面面。

備註

新增或更新引擎的功能時，文件團隊應該跟進。工作成果被合併後，如果需要文件，貢獻者應該在 godot-docs 倉庫建立 Issue。

請竭盡所能將文件保持在**1000 個單詞以內**。如果頁面超過了這個閾值，如果可能，請考慮將它拆分成兩個部分。對頁面的大小作出限制，強制我們在寫作時保持簡潔，將大段的文件進行拆分可以讓每一部分都集中於某個特定的問題。

講清楚每個頁面或章節所針對的**問題**，以及使用者會學到什麼。使用者需要知道他們看的指南是否能夠正確解決他們所遇到的問題。例如，請不要在題目裡寫“Signals”（訊號），請考慮寫“Reacting to changes with signals”（使用訊號對變化作出回應）。後者標明了使用訊號的目的。

備註

章節標題太長，側邊選單的專案就會變長，導覽也會變得冗長。請儘量讓題目保持在五個單詞以內。

如果某個頁面假設讀者瞭解引擎的另一項功能，請在開頭給出介紹和能夠為使用者提供必要資訊的資源連結。如果先決條件不在文件的範疇內，你也可以連結到其他網站。例如在數學章節中，你可以連結到入門指南中的程式設計簡介章節，也可以連結到某個教授數學理論的網站。

減少認知負擔

減少閱讀文件的認知負擔。我們使用的語言越簡單明瞭，大家學習起來效率就越高。你可以：

  1. 盡可能一次只介紹一個新概念。

  2. 就像在編寫規範中推薦的一樣，使用簡單的英語。

  3. 提供若干**實際使用範例**。現實世界的例子比像 foobar 一樣的抽象程式碼更好。

雖然很多人能夠理解複雜的語言和抽象的例子，你還是會失去其他人。而且，通俗易懂的寫作和實際的例子能讓所有人都受益。

始終努力**設身處地為使用者著想**。某件事情如果我們完全理解，對於我們而言就會變得顯而易見。我們可能無法想像新手相關的細節，但**好的文件就是要為使用者雪中送炭**。我們應該用盡可能直白的語言，盡力去解釋每一個功能的用處或用法。

回想一下學習某個功能或概念時，你首先需要瞭解的東西。你需要用到哪些新的術語？你困惑的點是什麼？最難掌握的是什麼？你會希望讓使用者對你的成果進行評審，我們建議你在著手寫作之前，先練習一下如何解釋這個功能。

備註

擁有程式設計基礎是使用像 Godot 這樣複雜的引擎的先決條件。你可以用到變數、函式、類。不過相對於“元程式設計”之類的特定術語，我們應該更傾向於使用平實的語言。如果你需要使用精准的術語，請一定要給出定義。