1.4 代码风格指南
标识符
在 Dart 中标识符有三种类型
•UpperCamelCase 每个单词的首字母都大写,包含第一个单词•lowerCamelCase 每个单词的首字母都大写,除了第一个单词, 第一个单词首字母小写,即使是缩略词•lowercase_with_underscores 只是用小写字母单词,即使是缩略词, 并且单词之间使用 _ 连接
要使用 UpperCamelCase 风格命名类型
Classes(类名)、 enums(枚举类型)、 typedefs(类型定义)、 以及 type parameters(类型参数)应该把每个单词的首字母都大写(包含第一个单词),不使用分隔符
代码语言:javascript复制class SliderMenu { ... }
class HttpRequest { ... }
typedef Predicate = bool Function<T>(T value);
这里包括使用元数据注解的类
代码语言:javascript复制class Foo { const Foo([arg]); }
@Foo(anArg) class A { ... }
@Foo() class B { ... }
要在库,包,文件夹,源文件中使用
代码语言:javascript复制lowercase_with_underscores 方式命名
Linter rules: library_names,[1] file_names[2]
要用 lowercase_with_underscores 风格命名库和源文件名
一些文件系统不区分大小写,所以很多项目要求文件名必须是小写字母。使用分隔符这种形式可以保证命名的可读性。使用下划线作为分隔符可确保名称仍然是有效的Dart标识符, 如果语言后续支持符号导入,这将会起到非常大的帮助。
代码语言:javascript复制library peg_parser.source_scanner;
import 'file_system.dart';
import 'slider_menu.dart';
library pegparser.SourceScanner;
import 'file-system.dart'; import 'SliderMenu.dart';
⚠️ 注意:如果你选择命名库,本准则给定了如何为库取名。如果需要,可以在文件中_省略_库指令
要使用 lowercase_with_underscores 风格命名导入的前缀
Linter rule: library_prefixes[3]
代码语言:javascript复制import 'dart:math' as math;
import 'package:angular_components/angular_components'
as angular_components;
import 'package:js/js.dart' as js;
import 'dart:math' as Math;
import 'package:angular_components/angular_components'
as angularComponents;
import 'package:js/js.dart' as JS;
要使用 lowerCamelCase 风格来命名其他的标识符
Linter rule: non_constant_identifier_names[4]
类成员、顶级定义、变量、参数以及命名参数等 除了第一个单词,每个单词首字母都应大写,并且不使用分隔符。
代码语言:javascript复制var item;
HttpRequest httpRequest;
void align(bool clearItems) {
// ...
}
推荐使用 lowerCamelCase 来命名常量
Linter rule: constant_identifier_names[5]
在新的代码中,使用 lowerCamelCase 来命名常量,包括枚举的值。已有的代码使用了 SCREAMING_CAPS 风格, 你可以继续全部使用该风格来保持代码的一致性
代码语言:javascript复制const pi = 3.14;
const defaultTimeout = 1000;
final urlScheme = RegExp('^([a-z] ):');
class Dice { static final numberGenerator = Random(); }
const PI = 3.14;
const DefaultTimeout = 1000;
final URL_SCHEME = RegExp('^([a-z] ):');
class Dice { static final NUMBER_GENERATOR = Random(); }
您可以使用 SCREAMING_CAPS 与现有代码保持一致,比如:
•将代码添加到已使用 SCREAMING_CAPS 的文件或库时。•生成与 Java 代码并行的 Dart 代码时。例如,来自 protobufs[6] 的枚举类型
注意:我们一开始使用 Java SCREAMING_CAPS 风格来命名常量。我们之所以不再使用,是因为:
•SCREAMING_CAPS 很多情况下看起来比较糟糕, 尤其类似于 CSS 颜色这类的枚举值•常量常常被修改为 final 类型的非常量变量, 这种情况你还需要修改变量的名字为小写字母形式•在枚举类型中自动定义的 values 属性为常量并且是小写字母 形式的
要把超过两个字母的首字母大写缩略词和缩写词当做一般单词来对待
首字母大写缩略词比较难阅读, 特别是多个缩略词连载一起的时候会引起歧义。例如,一个以 HTTPSFTP 开头的名字, 没有办法判断它是指 HTTPS FTP 还是 HTTP SFTP 。
为了避免上面的情况,缩略词和缩写词要像普通单词一样首字母大写, 两个字母的单词除外。(像 ID 和 Mr. 这样的双字母缩写词仍然像一般单词一样首字母大写。)
代码语言:javascript复制HttpConnectionInfo uiHandler IOStream HttpRequest Id DB
HTTPConnection UiHandler IoStream HTTPRequest ID Db
译者注:
•acronyms:首字母缩略词,指取若干单词首字母组成一个新单词,如:HTTP = HyperText Transfer Protocol•abbreviations: 缩写词,指取某一单词的部分字母(或其他缩短单词的方式)代表整个单词,如:ID = identification
不要 使用前缀字母
在编译器无法帮助你了解自己代码的时, 匈牙利命名法[7] 和其他方案出现在了 BCPL , 但是因为 Dart 可以提示你声明的类型,范围,可变性和其他属性, 所以没有理由在标识符名称中对这些属性进行编码。
代码语言:javascript复制defaultTimeout