Effective Dart

在过去的几年里，我们编写了大量的 Dart 代码，并学习了很多关于什么有效，什么无效的知识。我们与您分享这些，以便您也可以编写一致、健壮、快速的代码。这里有两个最重要的主题

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

   如果两段代码看起来不同，那应该是由于它们在某些有意义的方面是不同的。当一段代码突出并引起您的注意时，它应该出于有用的原因这样做。

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

   如果有很多种方式来说明某件事，您通常应该选择最简洁的一种。这并不是说您应该代码高尔夫，将整个程序塞进一行代码中。目标是经济而非密集的代码。

我们将指南分成几个单独的页面，以便于消化

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

• 文档指南 – 这告诉您关于注释内部内容的所有知识。包括文档注释和普通的、日常的代码注释。

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

• 设计指南 – 这是最柔性的指南，但范围最广。它涵盖了我们学到的关于为库设计一致、可用的 API 的知识。如果它在类型签名或声明中，则此处会介绍。

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

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

• DO 指南描述了应始终遵循的做法。几乎永远没有正当理由偏离它们。

• DON'T 指南是相反的：几乎永远不是好主意的事情。希望我们没有其他语言那么多这些，因为我们的历史包袱较少。

• PREFER 指南是您应该遵循的做法。但是，在某些情况下，这样做可能更有意义。只需确保您在忽略指南时充分理解其全部含义。

• AVOID 指南是“prefer”的双重：您不应该做的事情，但在极少数情况下可能有充分的理由这样做。

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

一些指南描述了规则不适用的例外情况。列出时，例外情况可能并不详尽 — 您可能仍然需要在其他情况下使用您的判断。

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

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

Linter 规则：unnecessary_getters_setters

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

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

• 库成员是顶层字段、getter、setter 或函数。基本上，顶层任何不是类型的东西。

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

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

• 变量，当一般使用时，指的是顶层变量、参数和局部变量。它不包括静态或实例字段。

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

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

除非另有说明，否则本网站上的文档反映的是 Dart 3.7.1 版本。页面上次更新于 2024-05-06。 查看源代码 或 报告问题。