目录

高效 Dart 语言指南

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

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

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

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

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

指南

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

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

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

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

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

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

如何阅读这些指南

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

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

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

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

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

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

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

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

Dart 分析器提供了一个 Linter 工具,可以帮助你编写优秀的、一致性的以及符合各种指南的代码。如果存在一个或者多个 linter 规则 来帮助你遵循某个指南准则,那么这些指南的链接也会有显示。比如下面的示例:

Linter rule: unnecessary_getters_setters

学习如何使用 linter,请查阅文档 启用 linter 规则,以及可用的各种 linter 规则

术语表

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

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

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

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

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

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

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

所有准则摘要

Usage

Libraries

Null

Strings

Collections

Functions

Variables

Members

Constructors

Error handling

Asynchrony

Design

Names

Libraries

Classes and mixins

Constructors

Members

Types

Parameters

Equality