-

名称

命名时应该采取驼峰大小写形式。

类、枚举以及自定义类型应该将每个单词的首字母大写(包括第一个词),并且不能使用分隔符。

// good
class SliderMenu {
  // ...
}

class HttpRequest {
  // ...
}

typedef num Adder(num x, num y);

最好使用 lowerCamelCase 的形式为常量命名。

一般使用 lowerCamelCase 的形式为常量命名,枚举类型中的值也应该采用这种形式。

如果已有的代码中采用全大写的方式为常量命名,那么你可以打开大写锁定以保持代码的一致性。

// good
const pi = 3.14;
const defaultTimeout = 1000;
final urlScheme = new RegExp('^([a-z]+):');

class Dice {
  static final numberGenerator = new Random();
}
// bad
const PI = 3.14;
const kDefaultTimeout = 1000;
final URL_SCHEME = new RegExp('^([a-z]+):');

class Dice {
  static final NUMBER_GENERATOR = new Random();
}

变动:在以前的代码中我们建议常量命名使用全大写。由于现在 const 从 final 中分离出来了,所以我们更改了命名的建议。当然,也有人希望枚举采用全大写的形式,但是我们希望以本指南当前的状况为准。

对于其他的标识符,应该使用 lowerCamelCase 的形式命名。

类的成员、全局定义、变量、参数以及命名的参数都应该将除了第一个单词以外的词语大写,并且不能使用分隔符。

//good
var item;

HttpRequest httpRequest;

align(clearItems) {
  // ...
}

对于在元数据注解中使用的类,应该采用 UpperCamelCase 的形式命名。

如果注解不需要任何参数,你可能希望为其创建一个 lowerCamelCase 形式的常量。

// good 
@Foo(anArg)
class A { ... }

@Foo()
class B { ... }

@foo
class C { ... }

对于库以及源文件,应该采用 lowercase_with_underscores 的形式命名。

有些文件系统是不区分大小写的,所以很多项目要求文件名应该全部采用小写的形式。这种情况下使用下划线将文件名中的单词分隔开,这样就可以使文件名依旧具有可读性。使用下划线作为分隔符的名称依旧是有效的 Dart 标识符,如果以后 Dart 增添了对符号引用的支持,那么该特性将会非常有用。

好的例子:

  • slider_menu.dart
  • file_system.dart
  • library peg_parser

坏的例子:

  • SliderMenu.dart
  • filesystem.dart
  • library peg-parser

声明库的前缀的时候应该采取 lowercase_with_underscores 的形式。

// good
import 'dart:math' as math;
import 'dart:json' as json;
import 'package:js/js.dart' as js;
import 'package:javascript_utils/javascript_utils.dart' as js_utils;
// bad
import 'dart:math' as Math;
import 'dart:json' as JSON;
import 'package:js/js.dart' as JS;
import 'package:javascript_utils/javascript_utils.dart' as jsUtils;

库名称的前面应该加上包名并且用 . 来分隔路径。

本指南将会帮助你避免因为两个库有相同名称而产生的警告。以下使我们推荐的一些规则:

  • 所有的库名称之前都加上包名作为前缀。
  • 入口库的名称应当和包名一致。
  • 对于包中的其他库,在包名后使用 . 来分隔库所对应的 Dart 文件所在路径。如果是 lib 下的库,名称中不用加入 lib。

举个例子,如果包名是 my_package。下面是该包中其他库文件的名称:

// good 
// In lib/my_package.dart
library my_package;

// In lib/other.dart
library my_package.other;

// In lib/foo/bar.dart
library my_package.foo.bar;

// In example/foo/bar.dart
library my_package.example.foo.bar;

// In lib/src/private.dart
library my_package.src.private;

对于超过两个字母的首字母缩略词以及缩写词,应该大写。

大写首字母缩略词可能有点难以阅读,并且当该词由相邻的多个单词构成时可能会导致歧义。像 HTTPSFTPConnection 这样的名称,你无法判断它究竟是 HTTPS FTP 连接还是 HTTP SFTP 连接。

为了避免出现这种情况,首字母缩略词以及缩写词还是像常规词语那样书写,如果只有两个字母的话,可以按照个人喜好命名。(两个字母的缩写词,像 ID 以及 Mr. 也可以想常规词语一样书写)

// good
HttpConnection
uiHandler
IOStream
HttpRequest
Id
id
Pt
DB
// bad
HTTPConnection
UiHandler
IoStream
HTTPRequest
ID
PT
Db