标识符
在 Dart 中标识符有三种风格:
- 大写驼峰:每个单词的第一个字母大写,包括第一个单词。
- 小写驼峰:每个单词的第一个字母大写,除了 第一个单词一直小写,即使第一个单词是缩写。
- 小写加下划线:只使用小写字母,即使是缩写,然后使用下划线
_
分隔。
类型名使用大写驼峰
类,枚举,自定义类型和参数类型,应该使用大写驼峰,且不能使用分隔符。
class SliderMenu { ... }
class HttpRequest { ... }
typedef bool Predicate<T>(T value);
甚至包括作为元数据注解的类。
class Foo {
const Foo([arg]);
}
@Foo(anArg)
class A { ... }
@Foo()
class B { ... }
如果注解类的构造函数没有参数,可以创建一个单独的小写驼峰常量。
const foo = const Foo();
@foo
class C { ... }
库和源文件名使用小写加下划线
一些文件系统是不区分大小写的,所以许多项目要求文件名全小写。使用分隔符使得那种方式下名字仍然可读。使用下划线作为分隔符确保名字仍然是有效的 Dart 标识符,这可能很有用,如果后续支持符号导入。
library peg_parser.source_scanner;
import 'file_system.dart';
import 'slider_menu.dart';
注意:该指南指定了如何命名一个库,如果你选择命名它。如果你想在文件中省略 library 指令也是可以的。
导入别名使用小写加下划线
import 'dart:math' as math;
import 'package:angular_components/angular_components'
as angular_components;
import 'package:js/js.dart' as js;
其它标识符使用小写驼峰
类成员,顶级的定义,变量,参数,命名参数使用小写驼峰。
var item;
HttpRequest httpRequest;
void align(bool clearItems) {
// ...
}
推荐常量名使用小写驼峰
在新代码中,对常量包括枚举值使用小写驼峰。在已存在代码继续使用全部大写加下划线,和之前保持一直。
const pi = 3.14;
const defaultTimeout = 1000;
final urlScheme = new RegExp('^([a-z]+):');
class Dice {
static final numberGenerator = new Random();
}
超过两个字母的首字母缩略词以及缩写词,应该大写
大写首字母缩略词有点难以阅读,并且多个相邻的缩写可能导致模棱两可的名字。例如,一个以HTTPSFTP
开始的名字,没有办法判断提及的是HTTPS FTP
还是HTTP SFTP
。
为了避免这种情况,除了两个字母的首字母缩略词以及缩写词,其它的还是像常规单词那样首字母大写。(两个字母的缩写词,像 ID 和 Mr. 仍然首字母大写。)
HttpConnectionInfo
uiHandler
IOStream
HttpRequest
Id
DB
顺序
为了保持文件的整洁,我们规定指令出现的顺序。每个部分应该使用空行隔开。
在其它导入之前导入 “dart:”
import 'dart:async';
import 'dart:html';
import 'package:bar/bar.dart';
import 'package:foo/foo.dart';
在相对导入之前导入 “package:”
import 'package:bar/bar.dart';
import 'package:foo/foo.dart';
import 'util.dart';
在其它导入前导入第三方 “package:”
import 'package:bar/bar.dart';
import 'package:foo/foo.dart';
import 'package:my_package/util.dart';
在所有导入之后的单独部分指定导出
import 'src/error.dart';
import 'src/foo_bar.dart';
export 'src/error.dart';
各部分内按字母顺序排序
import 'package:bar/bar.dart';
import 'package:foo/foo.dart';
import 'foo.dart';
import 'foo/foo.dart';
格式化
像其它语言,Dart 忽略空格。然而,人们不会。一致的空格风格确保人们看到的代码和编译器做的一样。
格式化是乏味的工作,在重构时特别花费时间。幸运的是,你不需要担心它。我们提供一个名为 dartfmt 的自动代码格式化程序,它可以帮你做这些。官方对 Dart 的空格处理规则是根据dartfmt生成的。
避免一行的长度超过 80 个字符
可读性研究表明,过长的文本不适合阅读,因为当你看到下一行开始的时候眼睛移动的距离过大。这就是为什么新闻和杂志使用多列的文本。
如果实际上你发现自己需要的行长度超过 80 个字符,我们的经验是你的代码可能太冗长了,可能需要更短小简洁。主要的问题通常是VeryLongCamelCaseClassNames
。问问你自己,“有必要名字中的每个单词都告诉我们一些类型信息或防止命名冲突吗?如果不,考虑省略它。
注意 dartfmt 为你做 99% 的事,但最后的 1% 是你的。它不会分离字符串字面量来符合 80 个字符,所以你必须手动去做。
有一个例外,是在导入和导出中,包含 URI 的字符串。它们可以保持单独一行,即使超出了一行 80 个字符的限制。这使得对于给出的路径更容易搜索源文件。
对所有流程控制结构使用大括号
这样避免了 else 悬挂的问题。
if (isWeekDay) {
print('Bike to work!');
} else {
print('Go dancing or read a book!');
}
有一个例外是:if
语句没有 else
,符合条件只有一行,可以省略大括号。
if (arg == null) return defaultValue;
这些典型的用于“守卫”代码,如果条件满足,返回或中断。但是它们也可以用于表达式,只要整个if
语句和表达式在同一行上。
if (parameter > limit) parameter = defaultValue;
使用 dartfmt 格式化代码
dartfmt 适用于下面所有规则连同其它一些微妙的启发式规则。它比你更快并且从不出错。如果你遵循这条规则,你可以跳过阅读剩下的指南。