文档编写指南

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 来描述布尔值

注解

技术作家的工作是将尽可能多的信息打包成尽可能最小和最清晰的句子.这些指南将帮助您实现这一目标.

英语清晰的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 以及可以用一个单词替换的任何表达之类的通用动词.

不要 重复该方法的名称,它已经声明,将枢轴值设置为一个新的值:

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

Do 解释这个 “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. [...]

请 使用简单的现在、过去或将来.

  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 := $Sprite as Sprite

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

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

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

  1. func choose(arguments: PoolStringArray) -> 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]

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

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

编写 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 来保持显式.``控制是否`` 可能不明确,且不适用于每个成员变量.

另外,在布尔值、变量名和方法周围用 [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 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).

属性检查器的可折叠区域是 部分(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屏幕截图,使用4xMSAA,对项目纹理启用各向异性过滤,并在项目设置中将各向异性过滤器质量设置为16x.

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

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

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

注解

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