Dart 风格指南

标识符

在 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 适用于下面所有规则连同其它一些微妙的启发式规则。它比你更快并且从不出错。如果你遵循这条规则,你可以跳过阅读剩下的指南

最后编辑于
©著作权归作者所有,转载或内容合作请联系作者
  • 序言:七十年代末,一起剥皮案震惊了整个滨河市,随后出现的几起案子,更是在滨河造成了极大的恐慌,老刑警刘岩,带你破解...
    沈念sama阅读 216,287评论 6 498
  • 序言:滨河连续发生了三起死亡事件,死亡现场离奇诡异,居然都是意外死亡,警方通过查阅死者的电脑和手机,发现死者居然都...
    沈念sama阅读 92,346评论 3 392
  • 文/潘晓璐 我一进店门,熙熙楼的掌柜王于贵愁眉苦脸地迎上来,“玉大人,你说我怎么就摊上这事。” “怎么了?”我有些...
    开封第一讲书人阅读 162,277评论 0 353
  • 文/不坏的土叔 我叫张陵,是天一观的道长。 经常有香客问我,道长,这世上最难降的妖魔是什么? 我笑而不...
    开封第一讲书人阅读 58,132评论 1 292
  • 正文 为了忘掉前任,我火速办了婚礼,结果婚礼上,老公的妹妹穿的比我还像新娘。我一直安慰自己,他们只是感情好,可当我...
    茶点故事阅读 67,147评论 6 388
  • 文/花漫 我一把揭开白布。 她就那样静静地躺着,像睡着了一般。 火红的嫁衣衬着肌肤如雪。 梳的纹丝不乱的头发上,一...
    开封第一讲书人阅读 51,106评论 1 295
  • 那天,我揣着相机与录音,去河边找鬼。 笑死,一个胖子当着我的面吹牛,可吹牛的内容都是我干的。 我是一名探鬼主播,决...
    沈念sama阅读 40,019评论 3 417
  • 文/苍兰香墨 我猛地睁开眼,长吁一口气:“原来是场噩梦啊……” “哼!你这毒妇竟也来了?” 一声冷哼从身侧响起,我...
    开封第一讲书人阅读 38,862评论 0 274
  • 序言:老挝万荣一对情侣失踪,失踪者是张志新(化名)和其女友刘颖,没想到半个月后,有当地人在树林里发现了一具尸体,经...
    沈念sama阅读 45,301评论 1 310
  • 正文 独居荒郊野岭守林人离奇死亡,尸身上长有42处带血的脓包…… 初始之章·张勋 以下内容为张勋视角 年9月15日...
    茶点故事阅读 37,521评论 2 332
  • 正文 我和宋清朗相恋三年,在试婚纱的时候发现自己被绿了。 大学时的朋友给我发了我未婚夫和他白月光在一起吃饭的照片。...
    茶点故事阅读 39,682评论 1 348
  • 序言:一个原本活蹦乱跳的男人离奇死亡,死状恐怖,灵堂内的尸体忽然破棺而出,到底是诈尸还是另有隐情,我是刑警宁泽,带...
    沈念sama阅读 35,405评论 5 343
  • 正文 年R本政府宣布,位于F岛的核电站,受9级特大地震影响,放射性物质发生泄漏。R本人自食恶果不足惜,却给世界环境...
    茶点故事阅读 40,996评论 3 325
  • 文/蒙蒙 一、第九天 我趴在偏房一处隐蔽的房顶上张望。 院中可真热闹,春花似锦、人声如沸。这庄子的主人今日做“春日...
    开封第一讲书人阅读 31,651评论 0 22
  • 文/苍兰香墨 我抬头看了看天上的太阳。三九已至,却和暖如春,着一层夹袄步出监牢的瞬间,已是汗流浃背。 一阵脚步声响...
    开封第一讲书人阅读 32,803评论 1 268
  • 我被黑心中介骗来泰国打工, 没想到刚下飞机就差点儿被人妖公主榨干…… 1. 我叫王不留,地道东北人。 一个月前我还...
    沈念sama阅读 47,674评论 2 368
  • 正文 我出身青楼,却偏偏与公主长得像,于是被迫代替她去往敌国和亲。 传闻我的和亲对象是个残疾皇子,可洞房花烛夜当晚...
    茶点故事阅读 44,563评论 2 352

推荐阅读更多精彩内容

  • 更新时间:2016/5/13 介绍 本文档所提供的编码规范,适用于主要的Python发行版中组成标准库的Pytho...
    超net阅读 5,859评论 0 15
  • 1、引言 数据库设计过程中表、字段等的命名规范也算是设计规范的一部分,不过设计规范更多的是为了确保数据库设计的合理...
    SnowflakeCloud阅读 40,988评论 0 48
  • 1 前言 这份文档是Google Java编程风格规范的完整定义。当且仅当一个Java源文件符合此文档中的规则,我...
    黑鼠_DEAN阅读 1,172评论 0 1
  • 一个统一的编程风格不但能够增强代码可读性,也可以避免许多低级问题。一个严格遵从编码规范的团队,代码无论出自多少人之...
    七弦桐语阅读 622评论 0 2
  • 能提高自己的写作水平吗,文字功底太差了。
    梅梅8888阅读 126评论 0 1