高效 Dart

在过去的几年里，我们编写了大量的 Dart 代码，并从中学习到了哪些有效，哪些无效。我们与您分享这些经验，以便您也能编写出一致、健壮、快速的代码。其中有两个总体主题：

1. 保持一致性。 当涉及到格式和大小写等问题时，关于哪个更好的争论是主观的，无法解决。我们知道的是，保持一致性客观上是有帮助的。

   如果两段代码看起来不同，那应该是因为它们在某种有意义的方式上确实不同。当一段代码引人注目时，它应该有一个有用的理由。

2. 简洁。 Dart 的设计旨在易于上手，因此它继承了 C、Java、JavaScript 和其他语言的许多相同语句和表达式。但我们创建 Dart 是因为这些语言所提供的功能仍有很大的改进空间。我们添加了许多功能，从字符串插值到初始化形式，以帮助您更简单、更容易地表达您的意图。

   如果有一种以上的方式来表达某件事，您通常应该选择最简洁的方式。这并不是说您应该像代码高尔夫一样把整个程序塞进一行。目标是代码要经济，而不是密集。

我们将这些指南分成几个独立的页面，以便于理解：

• 风格指南 – 这定义了代码布局和组织的规则，或者至少是 dart format 无法为您处理的部分。风格指南还指定了标识符的格式：camelCase、using_underscores 等。

• 文档指南 – 这告诉您有关注释内容所需的一切知识。包括文档注释和普通的、一般的代码注释。

• 用法指南 – 这教您如何最佳地利用语言特性来实现行为。如果它在语句或表达式中，这里都会涵盖。

• 设计指南 – 这是最“软”的指南，但范围最广。它涵盖了我们所学到的关于为库设计一致、可用 API 的知识。如果它在类型签名或声明中，这里都会涉及。

有关所有指南的链接，请参阅摘要。

每个指南都分为几个部分。每个部分包含一个指南列表。每个指南都以以下单词之一开头：

• DO（务必） 指南描述了应始终遵循的实践。几乎永远没有偏离它们的有效理由。

• DON'T（切勿） 指南是其反面：几乎永远不是好主意的事情。希望我们没有像其他语言那样多的这类指南，因为我们历史包袱较少。

• PREFER（优先） 指南是您应该遵循的实践。但是，在某些情况下，可能需要采取其他做法。只是在您这样做时，请务必了解忽略该指南的全部影响。

• AVOID（避免） 指南是“优先”的反面：您不应该做的事情，但极少数情况下可能有充分理由去做。

• CONSIDER（考虑） 指南是您可能或可能不希望遵循的实践，具体取决于情况、先例和您自己的偏好。

有些指南描述了规则不适用的例外情况。列出的例外可能不详尽——您可能仍需要根据其他情况进行判断。

这听起来像是如果您没有正确系好鞋带，警察就会破门而入。情况没那么糟。这里的大多数指南都是常识，我们都是通情达理的人。目标始终是编写出良好、可读且可维护的代码。

Dart 分析器提供了一个 Linter，可帮助您编写遵循这些及其他指南的良好、一致的代码。如果存在一个或多个可以帮助您遵循指南的linter 规则，则该指南会链接到这些规则。链接使用以下格式：

Linter 规则： unnecessary_getters_setters

要了解如何使用 Linter，请参阅启用 Linter 规则和Linter 规则列表。

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

• 库成员是顶层字段、getter、setter 或函数。基本上，顶层不是类型的所有内容。

• 类成员是类中声明的构造函数、字段、getter、setter、函数或运算符。类成员可以是实例或静态的，抽象或具体的。

• 成员是库成员或类成员。

• 变量，一般而言，指顶层变量、参数和局部变量。它不包括静态或实例字段。

• 类型是任何命名类型声明：类、typedef 或枚举。

• 属性是顶层变量、getter（在类中或顶层，实例或静态）、setter（同上）或字段（实例或静态）。大致是指任何“类字段”的命名构造。