开发者文档风格指南

动机

为了创建一个一致的平台，GNOME 模块必须拥有一致的文档，不仅在内容方面，而且在风格方面。统一的编辑声音有助于创建高质量、可读性和一致性的文档。

本风格指南编码了 GNOME 开发者文档使用的风格；它并不声称比其他风格指南客观上更好。本指南中的规则并非绝对：首先，您应该拥有可读的文档；如果结果不可读，您应该根据自己的判断行事。

重要的是要注意，本风格指南是一份动态文档：上下文和建议可能会随着时间的推移而变化，这些指南也会随之变化。您应该查看本文档的 更新内容 部分以了解更改。

声音和语调

文档应使用友好、对话式的语调。保持尊重和亲和力。直截了当，清晰明了，但不要迂腐和强求；就像朋友在他人需要时提供帮助一样。

  • 直奔主题。确保首先呈现关键信息；将其放在最显眼的位置。使步骤和选择显而易见。预先提供所有必要的信息。不要碍事。

  • 像人一样说话。口语化写作，但不要矫揉造作。不要完全按照您说话的方式写作，但可以自由使用日常用语和缩写。在解释事物时不要使用术语和缩写。不要使用流行文化参考或内部笑话。开发者文档是技术性的，但您仍然可以保持人性。保持个性化和令人难忘，并在需要时可以幽默。

  • 保持简单。不要不必要地冗长或迂腐。编写易于扫描和阅读的短句子。分解解释，并分层信息，以便人们可以在找到所需内容后停止阅读。

对于开发者文档，您可以假设读者将具备知识，但请记住，熟练程度各不相同；您的目标是让开发者实现他们的目标。

一些需要避免的事项

  • 流行语和术语

  • 歧视性语言

  • 占位符短语，例如请注意和目前

  • 冗长的句子

  • 所有句子都以相同的方式开头，例如您可以或要执行

  • 嘲笑其他项目或使用它们的人的笑话

  • 流行文化参考

  • 社区内部笑话

  • 感叹号

  • 混合隐喻

  • 晦涩的实现细节

  • 诸如简单地、这很简单、很容易、只是、快速地之类的短语

  • 网络俚语，例如tl;dr或ymmv

  • 过度使用请，例如请查看此文档或请使用此类

包容性写作

GNOME 致力于成为一个包容性的社区。我们的开发者文档应反映这一承诺。

全球受众

GNOME 用户和贡献者生活和工作在世界各地，您可以假设文档将由母语非英语的人阅读。

  • 编写短句子。考虑将包含多个从句和逗号的句子分解为多个句子。

  • 使用列表和表格。如果您有多个段落和复杂的句子，请考虑使用列表和表格代替。

  • 使用句子风格的 capitalization。仅大写专有名词，包括商标和项目和产品的名称。

  • 避免使用习语、口语表达和特定于文化的参考.

  • 避免堆砌修饰语。长长的修饰词链令人困惑，即使对于以英语为母语的人也是如此。

  • 使用主动语态.

  • 使形容词和副词靠近它们修饰的词.

  • 使用“that”、“who”和“which”来澄清句子结构.

性别认同和代词

除非您所指的人实际上是该性别，否则不要使用性别特定的代词。

特别是，不要将他、他、她或她作为中性代词，也不要使用他/她、(s)he或他或她或其他类似组合。相反，使用 单数“they”。

避免使用第一人称代词（我、我们、我们、我们的、我们的），除非

  • “常见问题解答”文档中的问题

  • 明确以第一人称撰写的文档

  • 一个句子引用您的项目或组织

尽可能使用第二人称代词。

对于关系代词，始终使用that、which和who来澄清句子结构。That和which不能互换

  • That引入限制性从句，并且前面没有逗号

  • Which引入非限制性从句，并且前面有逗号

在指人时，始终使用who。

在指人群、动物或事物时，可以使用whose。

避免沟通中的偏见

  • 在编写示例时，请注意刻板印象。选择姓名、性别认同和文化背景，以反映各种情况。

  • 不要对人、国家、地区和文化进行概括.

  • 不要使用俚语.

  • 不要使用粗俗或贬义词.

  • 不要使用带有种族偏见的术语。例如，不要使用master/slave之类的术语。使用primary/secondary或physical/logical，具体取决于上下文。与其替换一个词，不如重写以提高句子的清晰度；例如，与其将whitelist替换为allowlist，不如解释允许什么。

  • 关注人，而不是残疾。不要使用正常或健康等术语来描述没有残疾的人；避免使用委婉语，例如特殊或能力不同；避免使用去除人格的术语，例如四肢瘫痪，而使用四肢瘫痪的人。

  • 使用包容性语言.

格式

日期和时间

在表示时间时，使用 12 小时制，除非在需要 24 小时制的情况下

  • 使用确切的时间，格式为 HH:MM

  • 始终大写 AM 和 PM

  • 删除整点的时间的分钟数

对于范围，使用不带空格的连字符，例如：5-10 分钟前。

除非绝对必要，否则避免指定时区；使用时区的全名，并在括号中添加与 UTC 的偏移量，例如

  • 美国太平洋标准时间 (UTC-8)

  • 中欧夏令时 (UTC+2)

在表示日期时

  • 使用月份和星期几的全名，月份后跟日期，逗号，以及四位数的年份

  • 对于仅包含数字的日期，使用符合 ISO-8601 标准的 YYYY-MM-DD 格式

数字

  • 在使用序数时，在文本中拼写出来：first、second、tenth、twenty-first。

  • 拼写出零到九之间的数字。

  • 拼写出句子的开头数字。

  • 对于负数、分数、百分比、尺寸和十进制数，使用数字。

大写

  • 仅对顶级标题使用标题风格的大写，对其他所有内容使用句子风格的大写

    • 大写句子的第一个单词

    • 将其他单词小写

    • 当单词用斜杠连接时，如果第一个单词也大写，则大写第二个单词

  • 不要使用大写字母来强调。

  • 不要将所有字母小写作为一种风格选择。

  • 除非是品牌名称，否则不要使用内部大写。

  • 除非是品牌名称或专有名词，否则不要大写拼写的缩写词。

编写 API 参考

在记录 API 时，您应该提供完整的参考，通常是通过从源代码中通过文档注释生成它。

基础

API 参考必须提供以下内容的描述：

  • 每种类型：类、结构体、联合体、接口和枚举

  • 类、联合体和结构体内的每个公共字段

  • 类和接口内的每个虚拟函数

  • 枚举的每个成员

  • 每个常量

  • 每个函数和方法

  • 由类或接口定义的每个信号和属性

对于每种类型，都应该有一个简短的示例（25-50 行代码），说明如何使用该类型。

排版

  • 所有类型、函数、信号和属性名称应使用 code style

  • 字符串字面量，例如 XML 元素和属性，应使用 code style

  • 函数、方法和信号的参数应斜体。

  • 文档中类型名称应与代码中的类型名称匹配

    • 不要复数化类型名称。例如，不要使用 GtkButtons，而使用“GtkButton 实例”

类、结构体、接口、枚举

以简短的独特句子开始类型的描述，简要说明类型的目的，尤其是在不能立即从类型名称推断出来的情况下。

注意

第一句话通常将在索引中用作摘要，因此它应在 10-12 个单词的范围内。

  • 不要在第一句话中重复类型名称。

  • 不要说此类执行…或此类型将…。

对于具有公共字段的类和结构体，尽可能简短地描述每个字段。

可调用符号

可调用符号（如方法、函数和信号）的文档应简要说明执行的操作；说明先决条件和副作用；详细说明可能引发的错误；并指定任何相关的 API。

您应该使用现在时来描述所有内容。

  • 描述。描述应以描述操作的动词开头，将符号名称作为未说明的主语：将标签小部件添加到笔记本页面。

    • 如果符号是 getter 函数并且返回布尔值，则以检查是否…开头

    • 如果符号是 getter 函数并且返回布尔值以外的值，则以获取…或检索…开头

    • 如果符号是 setter 函数，则以设置…开头

    • 如果符号更新某些状态，则以更新…开头

    • 如果符号删除某些内容，则以删除…或移除…开头

    • 对于构造函数，以创建一个新的…开头

    • 对于回调函数，以由…调用开头

  • 参数。尽可能简短地描述。将任何详细信息放在可调用函数的描述中。

    • 以小写字母开头描述参数

    • 不要以句点结尾描述

    • 以“a”或“the”开头描述参数

    • 不要重复参数的类型

    • 对于描述操作的布尔参数，以如果为 true…或如果为 false…开头

    • 对于描述状态的布尔参数，使用格式如果为 true；否则为 false。在这些情况下，不要大写“true”和“false”，并且不要在常量上使用 code style

    • 不要在可为空参数的描述中包含或 NULL

    • 对于使用可变参数的参数，使用格式一个…列表

  • 返回值。尽可能简短地描述。将任何详细信息放在可调用函数的描述中。

    • 对于布尔返回值，使用格式如果为 true；否则为 false

    • 对于任何其他类型，以The…开头

    • 不要在可为空返回值的描述中包含或 NULL

  • 错误。如果函数设置 GError，请确保在可调用函数的描述中包含将要在出错时设置的域和代码。

属性

在描述属性时，包括 setter 和 getter 函数中的相同信息

  • 先决条件，例如有效值的范围

  • 副作用，例如更新属性会导致只读属性更改状态并发出通知

  • 默认值，如果对象根据属性是否在构造时设置来确定初始状态

代码示例

代码示例应说明如何以最惯用的方式使用特定的 API。您可以使用

  • 穿插在文本中的单行示例

  • 简短的自包含示例，展示单个功能

  • 长示例，展示多个功能

提供示例的作用介绍，以及它有什么要求和先决条件。

许多开发者会复制您提供的示例，并将其用作自己需求的基础。设计可重用的代码，并留下有关要修改的内容的注释。

不要包含复杂或曲折的代码；使示例易于扫描和理解。复杂的示例可以作为教程或深入文章的一部分。

不要在注释中说明显而易见的事情。

如果您为了简洁起见省略了示例的某一部分，请确保提供注释来解释您删除了什么。

显示预期的输出，必要时使用图片。

始终编译和测试示例代码。

确保示例代码遵循可访问性和安全性的最佳实践。

弃用

每当某个符号或类型被弃用时，请指定替换项以及弃用发生的版本。如果没有直接的替换项，请描述读者如何获得类似的结果。

最新内容

在本节中，我们将列出风格指南的更改，以便您可以轻松跟踪。