文档编写指南

Godot 社区丰富且具国际化。用户来自世界各地。他们中的一些人很年轻，很多人不是母语为英语的人。这就是为什么我们都必须使用清晰和通用的语言写作。对于类参考手册，目标是让每个人都能轻松和精确阅读。

总之，请始终尝试：

  1. 使用陈述句型

  2. 使用精确的动作动词

  3. 避免以 -ing 结尾的动词

  4. 删除不必要的副词和形容词。

  5. 禁止这 8 个词：obvious（显然）、simple（简单）、basic（基本）、easy（容易）、actual（实际）、just（仅仅）、clear（明显）、however（然而）

  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.

英语清晰的 7 条规则

使用陈述句型

尽可能使用陈述句型. 将你描述的类, 方法和常量作为主题. 使用被动语态编写是很自然的, 但它更难阅读并会产生更长的句子.

被动句:

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

主动句:

  1. The dog bit the man.

不要使用被动句型：

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

请将节点的名称用作名词：

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

使用精确的动作动词

优先使用精确而通用的动词, 而不要使用诸如 make, set 以及可以用一个单词替换的任何表达之类的通用动词.

不要重复该方法的名称。名称中已经表达了它会将 pivot 值设置为一个新的值：

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

请解释“set”的结果是什么：使用准确的动词，如 place、position、rotate、fade 等。

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

避免以 -ing 结尾的动词

使用进行时描述连续行动。例如：“is calling”、“is moving”。

不要使用进行时描述即时更改。

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

Do use simple present, past, or future.

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

例外：如果主语不清楚，替换“ing”动词算不上改进。例如，在前一句中，“it replaces”在“replacing”当前所在的位置没有多大意义。

你可以使用渐进式时态来描述在时间上连续的动作. 任何像动画或协同程序的东西.

小技巧

动词可以变成带有 -ing 的形容词名词。这不是动词时态变换，所以你可以使用它们：the remaining movement、the missing file 等等。

删除不必要的副词和形容词

写尽可能少的形容词和副词. 仅当它们在说明中添加关键信息时, 才使用它们.

不要使用冗余或无意义的副词。延长文档长度但不添加任何信息的词：

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

用一种简单的描述性语言写短句：

  1. A big texture [...]

禁止这 8 个词

不要 使用这8个被禁止的词:

  1. 显然(obvious)

  2. 简单(simple)

  3. 基本(basic)

  4. 容易(easy)

  5. 实际(actual)

  6. 仅仅(just)

  7. 明显(clear)

  8. however(某些用法)

游戏的创建和编程并不简单, 对于初次学习使用API的人来说, 更是如此. 列表中的其他单词, 如 just 或 actual, 不会在句子中添加任何信息. 也不要使用相应的副词:obviously, simply, basically, easily, actually, clearly.

不要 举例. 禁止使用的单词加长了说明, 并让注意力从最重要信息上移开:

  1. **TextureRect**
  2. 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.

请 删除它们:

  1. **TextureRect**
  2. [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节点页面上的第一句话:

  1. **Timer**
  2. A **simple** Timer node.

请 代替为解释节点的作用:

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

不要 用 “basic” , 太含糊:

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

请 使用简述来概述节点:

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

使用显式引用

支持显式引用而不是隐式引用.

不要 使用 “前者” , “后者” 等词语. 这些词在英语中并不是最常见的, 需要你去查阅参考资料.

  1. [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.

请 重复单词. 他们消除了所有歧义:

  1. [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”:

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

请 使用 's . 它使你可以将主要主题放在句子的开头, 并使其简短:

  1. 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.(这些物品黑白相间, 红黄相间, 蓝绿相间)

不要 让列表的最后一个元素不带逗号:

  1. Create a KinematicBody2D node, a CollisionShape2D node and a sprite node.

请 在有两个以上元素清单的最后一个元素 and 或 or 前加上逗号.

  1. Create a KinematicBody2D node, a CollisionShape2D node, and a sprite node.

如何编写方法和类

动态类型与静态类型

文档中的代码示例应遵循一致的样式, 以免混淆用户. 由于静态类型提示是GDScript的可选功能, 因此我们选择坚持编写动态代码. 这导致编写简洁明了的GDScript.

例外情况是向用户解释静态类型概念的主题.

不要 用冒号或强制转换添加类型提示:

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

Do 用动态类型编写常量和变量:

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

不要 用推断的参数或返回类型编写函数:

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

Do 使用动态类型来写函数:

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

在适当的情况下使用实际代码示例

对于初学者来说，比起抽象的 foo 和 bar，现实世界中的示例更容易被使用。您还可以直接从游戏项目中复制它们，以确保所有代码段都能正确编译。

编写 var speed = 10 而不是 var my_var = 10 可使初学者更好地理解代码. 它为他们提供了有关在实际项目中可以在何处使用代码段的参考框架.

不要写虚构的例子：

  1. onready var a = preload("res://MyPath")
  2. onready var my_node = $MyNode
  5. func foo():
  6.     # Do stuff

要写出具体事例：

  1. onready var sfx_player_gun = preload("res://Assets/Sound/SFXPlayerGun.ogg")
  2. onready var audio_player = $Audio/AudioStreamPlayer
  5. func play_shooting_sound():
  6.     audio_player.stream = sfx_player_gun
  7.     audio_player.play()

当然，有时候使用实际示例是不切实际的。在这种情况下，您仍应避免使用诸如 my_var、foo()、 my_func() 之类的名称，并考虑示例中更有意义的名称。

在简述中概述该节点

简述是参考手册中最重要的一句话。这是用户与节点的第一次接触：

  1. 这是“创建新节点”对话框中的唯一描述。

  2. 它位于参考手册中每个页面的顶部

简述应解释节点的角色及其功能，最多 200 个字符。

不要 写一些简短而含糊的摘要:

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

请 概述节点的功能:

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

如果可能的话, 请使用节点的完整描述来提供更多信息和代码示例.

如果它有用，请提及方法返回什么

一些方法返回重要值. 在描述的结尾, 最好在新行上描述它们. 对于名称以 set 或 get 开头的任何方法, 无需提及其返回值.

不要使用被动句型：

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

要始终使用“Returns”。

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

注意 陈述句 规则的例外: 通过移动方法, 外部对撞可以影响方法和调用 移动 的主体. 在这种情况下, 你可以使用被动语态.

使用“if true”来描述布尔值

对于布尔成员变量，总是使用 if true 和/或 if false 来保持显式。Controls whether or not 可能存在歧义，不适用于每个成员变量。

另外，在布尔值、变量名和方法周围用 [code][/code]。

请以“if true”开头：

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

在参数周围使用 [code]

在类参考手册中，始终使用 [code][/code] 包围参数。在文档和 Godot 中，它将显示为 这样。编辑 Godot 仓库中的 XML 文件时，请用 [code]this[/code] 替换现在的参数，如 ‘this’ 或 `this`。

Godot 文档中的常用词汇

开发人员选择了一些特定的单词来引用界面的区域. 它们在文档以及源代码中使用, 你应该始终使用它们而不是同义词, 因此用户知道你在谈论什么.

Overview of the interface and common vocabulary

界面和常用词汇概述

在编辑器的左上角是 main menu（主菜单）。中间按钮改变的是 workspace（工作区）。右上角的按钮是 playtest button（试玩按钮）。中间显示 2D 或 3D 空间的区域是 viewport（视图）。你可以在它顶部的 toolbar（工具栏）中找到 tool（工具）的列表。

视图两侧的选项卡或可停靠面板叫 dock（停靠面板），包括 FileSystem dock（文件系统面板）、包含场景树的 Scene dock（场景面板）、Import dock（导入面板）、Node dock（节点面板）、Inspector（检查器）也叫 Inspector dock（检查器面板）。如果使用的是默认布局，也可以把选项卡式的停靠面板称作 tab（选项卡）：Scene tab（场景选项卡）、Node tab（节点选项卡）……

视图底部的动画、调试器等是 panel（面板），它们一起构成了 bottom panel（底部面板）。

属性检查器的可折叠区域是 部分(sections). 你无法折叠的节点的父类名称是 类(Classes), 例如 KinematicBody2D class. 具有键值对的单独行是 属性(properties). 例如, 位置(position) 或 调整颜色(modulate color) 都是 属性(properties).

键盘快捷键指南

键盘和鼠标快捷方式应使用 `` :kbd:`` 标记, 该标记可使快捷方式在其余文本和内联代码中脱颖而出. 使用紧凑形式的修饰键( Ctrl/ Cmd)而不是其拼写形式( Control/ Command). 对于组合, 请在符号的两侧使用 + 符号.

确保提及与其他平台相比在 macOS 上不同的快捷方式。macOS 上的键盘快捷键一般会用 Cmd 代替 Ctrl。

尽量将快捷方式集成到句子中。例子如下，为了更好地展示而保留了 :kbd: 标记：

  • 按`` Ctrl + Alt + T’’ 来切换面板(在MacOS上为: Cmd + Alt + T``).

  • 按 :kbd:`Space` 并按住鼠标左键在2D编辑器中平移.

  • 按 :kbd:`Shift+Up Arrow` 可将节点向上移动8像素.

图像贡献指南

文档中很重要的一部分是图像，并且要遵循几个重要的准则。

首先，在截屏时应始终使用默认编辑器主题和文本。

对于 3D 屏幕截图，使用 4× MSAA，对项目纹理启用各向异性过滤，并在项目设置中将各向异性过滤质量设置为 16×。

屏幕截图尺寸不应超过 1920×1080，以确保在较慢的连接上快速加载。

当您需要高亮显示编辑器的某个区域以显示某些内容(如按钮或选项)时, 请使用不带倒角的2像素厚的黄色轮廓. 如果轮廓是在一个黑暗的背景, 轮廓应该是黄色的, 以便色盲的人可以很容易地看到. 请不要使用红色, 因为它对于某些用户来说是不可见的.

在你添加或替换文档中的任何图片之前, 它们应该通过运行PNG压缩器以节省尺寸. 你可以使用 Squoosh 中包含的无损OxiPNG压缩器来达到这个目的. 对于较大的图像, 可以考虑使用像 pngquant 的有损压缩器. 有了它, 在压缩过程中几乎没有图像质量损失.

注解

必须在本地安装 pngquant 程序，因为它在 Squoosh 中不可用。