在过去的几年里，我们编写了大量的 Dart 代码，并从中收获了很多经验和教训。我们将与你分享这些经验，这些经验将有助于你编写出一致、健壮、高效的代码。这里包含两主题：

1. 保持一致 当谈论到格式、命名以及参数的相关规则时，哪种规则更好，得出的结论通常是主观且无法达成一致的。但我们知道的是，客观上保持 一致 是非常有益的。

   如果两段代码看起来不同，那它们就应该有不同的含义。当一段突出的代码吸引到你的注意时，那它就应该有吸引你的理由。

2. 保持简洁 Dart 会让开发者感到很亲切，因为它继承了许多与 C、Java、JavaScript 及其他语言相同的语句和表达式语法。我们之所以开发 Dart 语言，是因为这些语言依然有很大的改进的空间。我们提供了很多新的特性，比如字符串插值、初始化范式等，以帮助你更简单、更轻松地表达意图。

   如果有多种方式来描述一件事情，那么你通常应该选择其中最简洁的方式。这并不意味着你要像 code golf（代码高尔夫挑战赛）一样将所有代码塞到一行中。而是应该让代码变得 简约 而非 密集。

Dart Analyzer 中有一个 Linter 工具，该工具可以帮助你编写优秀的、一致性的代码。如果存在一个 Linter 规则可以帮助你遵循某个指南准则，那么该指南准则将链接到该规则。比如下面的示例：

Linter rule: prefer_collection_literals

更多关于 开启 Linter 规则 的帮助，请查阅 自定义静态分析 文档。

指南

为了便于理解，这里我们将指南分成了几个部分：

• 风格指南 – 该部分定义了布局和组织代码的规则，或者说是 dart format 不能为你格式化的那些代码的布局和组织规则。风格指南还为你指定了标识符的格式，比如：驼峰式大小写、下划线的使用等等。

• 注释指南 – 该部分会告诉你注释中应该包含哪些内容。包括文档注释以及常规的普通代码注释。

• 使用指南 – 该部分将教你如何充分利用语言特性来实现相关功能。比如你可以在该部分找到如何利用语句或表达式来实现某个功能。

• 设计指南 – 该部分是最易理解但是覆盖范围最广的。其涵盖了我们所总结的为库设计一致、可用 API 的经验。比如这些 API 的类型签名或声明的说明则会在这里找到。

有关所有指南的链接，请查阅 概览。

如何阅读这些指南

每个指南都分为了几个部分。每个部分包含一些详细的准则。每条准则都以下面其中的一个词作为开头：

• 要 准则所描述的内容应该始终被遵守。不应该以任何的理由来偏离违背这些准则。

• 不要 准则所描述的内容是相反的：描述的准则不是一个好注意。幸运的是，我们不会像其他语言有那么多这样的准则，因为我们没有太多的历史包袱。

• 推荐 准则所描述的内容 应该 被遵守。但是在有些情况下，可能有更好的或者更合理的做法。请确保在你完全理解准则的情况下，再忽视这些准则。

• 避免 该单词描述的准则与 “推荐” 描述的准则相反：显然，这些事不应该做，但不排除在极少数场合下有充分的理由可以做。

• 考虑 准则所描述的内容可以遵守也可以不遵守。取决于具体的情况、习惯做法以及自己的偏好。

某些准则描述了规则 不 适用的 例外情况。当这些例外列出时，也有可能不是详尽的—你可能还需要对其它的情况作出判断。

这听起来好像有点小题大做。其实并没有那么糟糕。大部分的准则都是常识，也符合我们的认知。最终要达到的目标是写出优雅，可读，可维护的代码。

术语表

为了使指南保持简洁，我们使用一些简写术语来指代不同的 Dart 结构。

• 库成员 表示一个顶层字段、Getter 或 Setter 方法、或函数。基本而言，任何顶层的东西都不会是一种类型。

• 类成员 表示类内部声明的构造函数、字段、Getter 或 Setter 方法、函数或操作符。类成员可以是实例或静态的，也可以是抽象或具体的。

• 成员 可以表示是一个库成员或者类成员。

• 变量 通常指的是顶层变量、参数和局部变量。它不包括静态或实例字段。

• 类型 表示所有命名类型的声明：一个类、typedef 或枚举。

• 属性 表示顶层变量、Getter 和 Setter 方法（位于类中或顶层，可以是实例或静态的）或字段（实例或静态的）。基本上是任何类似字段的命名结构都可以称为属性。

所有准则摘要