Effective Dart: 文档

目录 keyboard_arrow_down keyboard_arrow_up

注释
- 像句子一样格式化注释
- 不要将块注释用于文档
文档注释
Markdown
写作

more_horiz

人们很容易认为你今天的代码很明显，而没有意识到你有多么依赖脑海中已有的上下文。新接触你代码的人，甚至是健忘的未来的你，都不会有这种上下文。编写一个简洁、准确的注释只需几秒钟，但可以为这些人节省数小时的时间。

我们都知道代码应该自我文档化，而且并非所有注释都有帮助。但现实是，我们大多数人都没有写足够多的注释。这就像锻炼：从技术上讲，你可以做太多，但更有可能的是你做得太少。尝试加强它。

以下提示适用于您不希望包含在生成的文档中的注释。

gooddart// Not if anything comes before it.
if (_chunks.isNotEmpty) return false;

首字母大写，除非它是区分大小写的标识符。以句点（或“！”或“？”）结尾。这适用于所有注释：文档注释、内联内容，甚至是 TODO。即使它只是一个句子片段。

gooddartvoid greet(String name) {
  // Assume we have a valid name.
  print('Hi, $name!');
}

baddartvoid greet(String name) {
  /* Assume we have a valid name. */
  print('Hi, $name!');
}

您可以使用块注释 (/* ... */) 来临时注释掉一段代码，但所有其他注释都应该使用 //。

文档注释尤其方便，因为 dart doc 会解析它们并从中生成漂亮的文档页面。文档注释是出现在声明之前并使用 dart doc 查找的特殊 /// 语法的任何注释。

Linter 规则: slash_for_doc_comments

使用文档注释而不是普通注释可以使 dart doc 找到它并为其生成文档。

gooddart/// The number of characters in this chunk when unsplit.
int get length => ...

baddart// The number of characters in this chunk when unsplit.
int get length => ...

由于历史原因，dart doc 支持两种文档注释语法：/// (“C# 风格”) 和 /** ... */ (“JavaDoc 风格”)。我们首选 ///，因为它更紧凑。/** 和 */ 会向多行文档注释添加两行无内容的行。在某些情况下，/// 语法也更容易阅读，例如当文档注释包含使用 * 标记列表项的带项目符号的列表时。

如果您偶然发现仍然使用 JavaDoc 风格的代码，请考虑清理它。

Linter 规则: public_member_api_docs

您不必为每个库、顶级变量、类型和成员都编写文档，但您应该为它们中的大多数编写文档。

与 Java 等类是程序组织的唯一单元的语言不同，在 Dart 中，库本身就是一个用户直接使用、导入和思考的实体。这使得 library 指令成为一个绝佳的地方，可以用来介绍读者库中提供的主要概念和功能。考虑包括

库用途的单句摘要。
对整个库中使用的术语的解释。
几个完整的代码示例，演示如何使用 API。
指向最重要或最常用的类和函数的链接。
指向与库相关的域的外部参考文献的链接。

要记录库，请在 library 指令以及可能附加在文件开头的任何注释之前放置文档注释。

gooddart/// A really great test library.
@TestOn('browser')
library;

文档注释不仅适用于您库的公共 API 的外部使用者。它们对于理解从库的其他部分调用的私有成员也很有帮助。

以简短的、以用户为中心的描述开头您的文档注释，并以句号结尾。一个句子片段通常就足够了。为读者提供足够的上下文来定位自己，并确定他们应该继续阅读还是在其他地方寻找问题的解决方案。

gooddart/// Deletes the file at [path] from the file system.
void delete(String path) {
  ...
}

baddart/// Depending on the state of the file system and the user's permissions,
/// certain operations may or may not be possible. If there is no file at
/// [path] or it can't be accessed, this function throws either [IOError]
/// or [PermissionError], respectively. Otherwise, this deletes the file.
void delete(String path) {
  ...
}

在第一句话后添加一个空行，将其拆分为单独的段落。如果需要超过一句话的解释，请将其余部分放在后面的段落中。

这有助于您编写一个简洁的第一句话来总结文档。此外，dart doc 等工具会在类和成员列表等位置使用第一段作为简短摘要。

gooddart/// Deletes the file at [path].
///
/// Throws an [IOError] if the file could not be found. Throws a
/// [PermissionError] if the file is present but could not be deleted.
void delete(String path) {
  ...
}

baddart/// Deletes the file at [path]. Throws an [IOError] if the file could not
/// be found. Throws a [PermissionError] if the file is present but could
/// not be deleted.
void delete(String path) {
  ...
}

类的文档注释的读者可以清楚地看到类的名称，它实现了哪些接口等等。在阅读成员的文档时，签名就在那里，并且封闭类是显而易见的。这些都不需要在文档注释中说明。相反，请专注于解释读者不知道的内容。

gooddartclass RadioButtonWidget extends Widget {
  /// Sets the tooltip to [lines], which should have been word wrapped using
  /// the current font.
  void tooltip(List<String> lines) {
    ...
  }
}

baddartclass RadioButtonWidget extends Widget {
  /// Sets the tooltip for this radio button widget to the list of strings in
  /// [lines].
  void tooltip(List<String> lines) {
    ...
  }
}

如果您真的没有什么有趣的事情可说，而这些内容又不能从声明本身推断出来，则省略文档注释。与其浪费读者的时间告诉他们他们已经知道的内容，不如什么都不说。

文档注释应侧重于代码做什么。

gooddart/// Returns `true` if every element satisfies the [predicate].
bool all(bool predicate(T element)) => ...

/// Starts the stopwatch if not already running.
void start() {
  ...
}

文档注释应该强调属性是什么。即使对于可能进行计算或其他工作的 getter 也是如此。调用者关心的是该工作的结果，而不是工作本身。

gooddart/// The current day of the week, where `0` is Sunday.
int weekday;

/// The number of checked buttons on the page.
int get checkedCount => ...

文档注释应该阐明此变量表示的状态。即使对于可能进行计算或其他工作的 getter 也是如此。调用者关心的是该工作的结果，而不是工作本身。

gooddart/// Whether the modal is currently displayed to the user.
bool isVisible;

/// Whether the modal should confirm the user's intent on navigation.
bool get shouldConfirm => ...

/// Whether resizing the current browser window will also resize the modal.
bool get canResize => ...

如果一个属性同时具有 getter 和 setter，则只需为其中一个创建文档注释。dart doc 将 getter 和 setter 视为一个字段，如果 getter 和 setter 都具有文档注释，则 dart doc 将丢弃 setter 的文档注释。

gooddart/// The pH level of the water in the pool.
///
/// Ranges from 0-14, representing acidic to basic, with 7 being neutral.
int get phLevel => ...
set phLevel(int level) => ...

baddart/// The depth of the water in the pool, in meters.
int get waterDepth => ...

/// Updates the water depth to a total of [meters] in height.
set waterDepth(int meters) => ...

类的文档注释通常是程序中最重要的文档。它们描述了类型的不变量，确立了它使用的术语，并为类的其他成员的文档注释提供上下文。在此处稍加努力可以使其他成员的文档编写更加简单。

gooddart/// A chunk of non-breaking output text terminated by a hard or soft newline.
///
/// ...
class Chunk { ... }

gooddart/// Returns the lesser of two numbers.
///
/// ```dart
/// min(5, 3) == 3
/// ```
num min(num a, num b) => ...

人类擅长从示例中进行概括，因此即使是单个代码示例也能使 API 更容易学习。

Linter 规则：comment_references

如果您将变量、方法或类型名称等内容用方括号括起来，则 dart doc 会查找该名称并链接到相关的 API 文档。括号是可选的，但当您引用方法或构造函数时，可以使其更清晰。

gooddart/// Throws a [StateError] if ...
/// similar to [anotherMethod()], but ...

要链接到特定类的成员，请使用类名和成员名，用点分隔

gooddart

/// Similar to [Duration.inDays], but handles fractional days.

点语法还可用于引用命名构造函数。对于未命名的构造函数，请在类名后使用 .new

gooddart

/// To create a point, call [Point.new] or use [Point.polar] to ...

其他语言使用冗长的标签和部分来描述方法的参数和返回值。

baddart/// Defines a flag with the given name and abbreviation.
///
/// @param name The name of the flag.
/// @param abbr The abbreviation for the flag.
/// @returns The new flag.
/// @throws ArgumentError If there is already an option with
///     the given name or abbreviation.
Flag addFlag(String name, String abbr) => ...

Dart 中的约定是将此集成到方法描述中，并使用方括号突出显示参数。

gooddart/// Defines a flag.
///
/// Throws an [ArgumentError] if there is already an option named [name] or
/// there is already an option using abbreviation [abbr]. Returns the new flag.
Flag addFlag(String name, String abbr) => ...

gooddart/// A button that can be flipped on and off.
@Component(selector: 'toggle')
class ToggleComponent {}

baddart@Component(selector: 'toggle')
/// A button that can be flipped on and off.
class ToggleComponent {}

您可以在文档注释中使用大多数 markdown 格式，并且 dart doc 将使用 markdown 包对其进行相应处理。

已经有很多指南向您介绍 Markdown。它之所以被普遍使用，正是我们选择它的原因。这里只是一个快速示例，让您了解一下支持的内容

dart/// This is a paragraph of regular text.
///
/// This sentence has *two* _emphasized_ words (italics) and **two**
/// __strong__ ones (bold).
///
/// A blank line creates a separate paragraph. It has some `inline code`
/// delimited using backticks.
///
/// * Unordered lists.
/// * Look like ASCII bullet lists.
/// * You can also use `-` or `+`.
///
/// 1. Numbered lists.
/// 2. Are, well, numbered.
/// 1. But the values don't matter.
///
///     * You can nest lists too.
///     * They must be indented at least 4 spaces.
///     * (Well, 5 including the space after `///`.)
///
/// Code blocks are fenced in triple backticks:
///
/// ```dart
/// this.code
///     .will
///     .retain(its, formatting);
/// ```
///
/// The code language (for syntax highlighting) defaults to Dart. You can
/// specify it by putting the name of the language after the opening backticks:
///
/// ```html
/// <h1>HTML is magical!</h1>
/// ```
///
/// Links can be:
///
/// * https://www.just-a-bare-url.com
/// * [with the URL inline](https://google.com)
/// * [or separated out][ref link]
///
/// [ref link]: https://google.com
///
/// # A Header
///
/// ## A subheader
///
/// ### A subsubheader
///
/// #### If you need this many levels of headers, you're doing it wrong

如有疑问，请减少格式设置。格式设置的存在是为了阐明您的内容，而不是替换它。文字才是最重要的。

在极少数情况下，例如表格，使用它可能会有用，但在几乎所有情况下，如果它太复杂而无法用 Markdown 表达，那么最好不要表达它。

Markdown 有两种方式来指示代码块：在每行代码前缩进四个空格，或者将其用一对三反引号“围栏”行括起来。当在 Markdown 列表等内部使用时，前一种语法很脆弱，因为缩进已经有意义，或者当代码块本身包含缩进的代码时。

反引号语法避免了那些缩进的麻烦，让您指示代码的语言，并且与使用反引号表示内联代码一致。

gooddart/// You can use [CodeBlockExample] like this:
///
/// ```dart
/// var example = CodeBlockExample();
/// print(example.isItGreat); // "Yes."
/// ```

baddart/// You can use [CodeBlockExample] like this:
///
///     var example = CodeBlockExample();
///     print(example.isItGreat); // "Yes."

我们认为自己是程序员，但源文件中的大多数字符主要是供人类阅读的。英语是我们用来修改同事大脑的代码语言。对于任何编程语言来说，都值得努力提高您的熟练程度。

本节列出了我们文档的一些指导原则。您可以从诸如技术写作风格之类的文章中了解有关技术写作最佳实践的更多信息。

清晰、准确，但也简洁。

很多人不知道 “i.e.”、“e.g.” 和 “et al.” 的含义。您确信您所在领域的每个人都知道的缩写可能并不像您想象的那么广为人知。

当为一个类的成员编写文档时，您通常需要引用调用该成员的对象。使用 “the” 可能存在歧义。

dartclass Box {
  /// The value this wraps.
  Object? _value;

  /// True if this box contains a value.
  bool get hasValue => _value != null;
}

除非另有说明，否则本网站上的文档反映了 Dart 3.6.0。页面上次更新时间为 2024-12-11。查看源代码或报告问题。

Effective Dart: 文档

注释

像句子一样格式化注释

不要将块注释用于文档

文档注释

使用 `///` 文档注释来记录成员和类型

首选为公共 API 编写文档注释

考虑编写库级文档注释

考虑为私有 API 编写文档注释

文档注释以一个单句摘要开头

将文档注释的第一句话分成单独的段落

避免与周围上下文冗余

首选以第三人称动词开头编写函数或方法注释

首选以名词短语开头编写非布尔变量或属性注释

首选以 "Whether" 开头，后跟名词或动名词短语来编写布尔变量或属性注释

不要为属性的 getter 和 setter 都编写文档

首选以名词短语开头编写库或类型注释

考虑在文档注释中包含代码示例

在文档注释中使用方括号来引用范围内的标识符

使用散文来解释参数、返回值和异常

将文档注释放在元数据注解之前

Markdown

避免过度使用 markdown

避免使用 HTML 进行格式化

首选使用反引号围栏表示代码块

写作

首选简洁

除非缩写和首字母缩略词很明显，否则避免使用

首选使用 "this" 而不是 "the" 来引用成员的实例

Effective Dart: 文档

注释

像句子一样格式化注释

不要将块注释用于文档

文档注释

使用 /// 文档注释来记录成员和类型

首选为公共 API 编写文档注释

考虑编写库级文档注释

考虑为私有 API 编写文档注释

文档注释以一个单句摘要开头

将文档注释的第一句话分成单独的段落

避免与周围上下文冗余

首选以第三人称动词开头编写函数或方法注释

首选以名词短语开头编写非布尔变量或属性注释

首选以 "Whether" 开头，后跟名词或动名词短语来编写布尔变量或属性注释

不要为属性的 getter 和 setter 都编写文档

首选以名词短语开头编写库或类型注释

考虑在文档注释中包含代码示例

在文档注释中使用方括号来引用范围内的标识符

使用散文来解释参数、返回值和异常

将文档注释放在元数据注解之前

Markdown

避免过度使用 markdown

避免使用 HTML 进行格式化

首选使用反引号围栏表示代码块

写作

首选简洁

除非缩写和首字母缩略词很明显，否则避免使用

首选使用 "this" 而不是 "the" 来引用成员的实例

使用 `///` 文档注释来记录成员和类型