Ⅰ	Ⅱ	Ⅲ	Ⅳ
Style Guide💅	Usage Guide🔖	Documentation Guide📃	Design Guide💎

What is the project ?

	// dart language 
	void main() {
		Map repo = new Map()
		  ..addAll({'name':'Effective Dart 中文版'})
		  ..addAll({'author':'雷仔'})
                  ..allAll({'lang':'中文'})
		  ..adddAll({'status':'work in progress'});
		print(repo);
	}

Table of contents

🔥 Effective Dart: Style 🔥

1. 标识符命名
   • [DO] 类型命名使用大写驼峰风格
   • [DO] 库个源文件命名使用小写加下划线风格
   • [DO] import前缀命名使用小写加下划线风格
   • [DO] 其他命名使用小写驼峰风格
   • [PREFER] 常量命名使用小写驼峰风格
   • [DO] 缩略词大写
   • [DON'T] 不要使用前缀字符
2. 代码顺序
   • [DO] 将dart:xx导入代码放在其他导入之前
   • [DO] 将package:xx导入代码放在相对文件导入之前
   • [PREFER] 将自己的包的引入代码放在其他三方包引入之后
   • [DO] 导出代码应该放在所有导入代码之后
   • [DO] 同一类导入代码顺序根据文件或者包名的首字母排序
3. 格式化
   • [DO] 使用dartfmt工具格式化你的代码
   • [CONSIDER] 修改你的代码使之变得对格式化工具友好
   • [AVOID] 单行代码不超过80个字符
   • [DO] 使用大括号包裹你的控制流结构

Effective Dart: Usage

• 库
  • [DO] part of指令之后使用字符串
  • [DON'T] 不要在你的库的src目录下引入其他库
  • [PREFER] 库lib目录下的引入请使用相对路径
• 字符串
  • [DO] 使用adjacent strings串联字符串而不是使用+号
  • [PREFER] 使用模板字符串来拼接值和字符而不是用+拼接
  • [AVOID] 在不需要使用大括号时省略大括号
• 集合
  • [DO] 尽量使用字面量定义集合
  • [DON'T] 不要使用.length去判断集合是否为空
  • [CONSIDER] 使用高阶函数对集合进行转换处理
  • [AVOID] 避免在Iterable.forEach()里写函数
  • [DON'T] 不要使用List.from()除非你想转换集合类型
  • [DO] 使用whereType()去过滤集合类型
  • [DON'T] 当其他操作符可以转换类型时不要使用cast()
  • [AVOID] 避免使用cast()
• 函数
  • [DO] 直接声明函数而不是将lambda函数赋值给一个变量
  • [DON'T] lambda表达式尽量简洁
• 参数
  • [DO] 使用=为吗命名参数设置默认值
  • [DON'T] 不要将默认值显式设置为null
• 变量
  • [DON'T] 不要将初始化变量显式设置为null
  • [AVOID] 避免存储你可以计算的值
• 成员
  • [DON'T] 不要在不必要的时候设置getter和setter
  • [PREFER] 使用final声明一个只读属性
  • [CONSIDER] 对于一个简单属性的获取使用=>
  • [DON'T] 不要在不必要的时候使用this
  • [DO] 尽量在初始值声明时赋值初始值
• 构造函数
  • [DO] 尽量使用简洁的构造函数声明方式
  • [DON'T] 不要为构造函数参数声明类型
  • [DO] 构造函数body为空时使用;而不是{}
  • [DON'T] 不要使用new关键字声明实例
  • [DON'T] 不要重复冗余的声明const
• 错误处理
  • [AVOID] 避免在没有条件控制下捕捉错误
  • [DON'T] 不要忽略错误
  • [DO] 仅仅在语法错误的情况下抛出实现Error的类
  • [DON'T] 开发时不要对错误做处理，let's crash
  • [DO] 使用rethrow关键词重新抛出无法处理的异常
• 异步
  • [PREFER] 使用async/await优于传统的Future
  • [DON'T] 不要在async没有任何作用时使用它
  • [CONSIDER] 使用高阶函数处理转换流stream
  • [AVOID] 避免直接使用Completer类
  • [DO] 当参数声明类型为Future<T>时候，参数可能为Object的情况下请用Future<T>做类型判断

Effective Dart: Documentation

• 注释
  • [DO] 用描述性的语句写注释
  • [DON'T] 使用块注释作为文档
• 文档注释
  • [DO] 使用\\\文档注释去注释成员和类型
  • [PREFER] 为公共API写文档注释
  • [CONSIDER] 编写库级别的文档注释
  • [CONSIDER] 为私有API编写文档注释
  • [DO] 使用一句话完成文档总结
  • [DO] 将文档注释段落的第一句话分离出来
  • [AVOID] 注释避免冗余
  • [PREFER] 注释函数或者方法时使用第三人称动词
  • [PREFER] 注释变量，getter/setter时使用名词短语
  • [PREFER] 注释库或者类型时使用名词短语
  • [CONSIDER] 在注释中提供代码例子
  • [DO] 在文档注释中使用方括号突出作用域內标识符
  • [DO] 使用简介的描述来注释参数，返回值和抛出的异常
  • [DO] 将文档注释放在元数据注解@之前
• Markdown
  • [AVOID] 避免过度使用Markdown
  • [AVOID] 避免使用HTML作为注释
  • [PREFER] 使用反引号来区分代码块
• 书写
  • [PREFER] 尽量简短
  • [AVOID] 尽量避免使用缩略词除非它们很常见
  • [PREFER] 使用this而不是the去指代实例本身

Effective Dart: Design

WIP (work in progress)

• 命名
  • [DO] 使用统一的命名策略
  • [AVOID] 避免使用缩写
  • [PREFER] 将最有意义的描述名词放在最后
  • [CONSIDER] 增加代码可读性，使之语义化
  • [PREFER] 非布尔值的属性或者变量命名使用名词短语
  • [PREFER] 布尔值属性或者变量命名使用非命令性动词
  • [CONSIDER] 布尔值命名参数请省略动词
  • [PREFER] 布尔值属性或者变量命名时使用正面词汇命名
  • [PREFER] 当函数或者方法会产生副作用时用动词短语命名
  • [PREFER] 当函数或者方法有返回值时用名词短语命名
  • [CONSIDER] 如果你想强调函数工作内容请用动词短语命名
  • [AVOID] 避免使用get作为函数方法名字的开头
  • [PREFER] 如果是将一个对象状态复制到另一个对象的方法请使用to_()格式命名
  • [PREFER] 改变对象类型使用as_()格式命名
  • [AVOID] 不要在函数方法名中出现参数名
  • [DO] 当给类型参数命名时请遵循如下的助记符约定
• 库
  • [PREFER] 声明为私有
  • [CONSIDER] 可以在同一个库里声明多个类
• 类
  • [AVOID] 避免定义单成员抽象类使用函数替代
  • [AVOID] 避免定义只含一个静态成员的类
  • [AVOID] 避免继承不想拥有子类的类
  • [DO] 如果你的类支持继承请在文档里说明
  • [AVOID] 避免实现不支持作为接口的类
  • [DO] 如果你的类支持作为借口请在文档里说明
  • [AVOID] 避免混合mixin不支持作为mixin的类
  • [DO] 如果你的类支持作为mixin请在文档里说明
• 构造函数
  • [PREFER] 建议定义构造函数而不是静态方法去生成实例
  • [CONSIDER] 如果类支持请将构造函数声明为const
• 类成员
  • [PREFER] 将顶级作用域的变量声明为final
  • [DO] 为可获得的属性添加getters
  • [DO] 为可设置的属性添加setters
  • [DON'T] 不要定义setters时不定义对应的getters
  • [AVOID] 避免返回值返回null
  • [AVOID] 避免直接返回this,链式调用请用cascade也就是..运算符
• 类型
  • [PREFER] 声明顶级作用域变量类型
  • [CONSIDER] 声明私有作用域变量类型
  • [AVOID] 避免声明初始化本地变量类型
  • [AVOID] 避免在闭包中声明推断参数的类型
  • [AVOID] 避免在使用泛型时重复冗余的声明类型
  • [DO] 当推断类型时确定类型时请声明类型
  • [PREFER] 使用dynamic声明类型而不是让推断直接fail掉
  • [PREFER] 当函数作为参数时请声明函数类型
  • [DON'T] 不要为setter声明类型
  • [DON'T] 不要使用遗留版本的typedef语法
  • [PREFER] 使用函数类型声明而不是typedef
  • [CONSIDER] 函数作为参数时使用函数类型语法
  • [DO] 当参数可以是任意类型时用Object声明而不是dynamic
  • [DO] 当异步函数不返回值时使用Future<void>声明
  • [AVOID] 避免使用FutureOr<T>作为返回类型
• 参数
  • [AVOID] 避免布尔值类型位置参数
  • [AVOID] 如果你想省略一些参数请请避免使用位置参数
  • [AVOID] 避免强制性参数当参数可以省略时
  • [DO] 获取范围时将参数设置为左闭右开
• 相等符
  • [DO] 如果你重载==请一并重载hashcode
  • [DO] 请让你的==运算符遵守数学上的相等
  • [AVOID] 避免为可变类定义常规意义上的相等
  • [DON'T] 不需要在重载==运算符时判断类型是否为null

Find a job?（:office: : Shanghai,China）:point_down:

上海寻梦科技（拼多多） 高速上升期，招聘算法-前端-客户端-Java开发-Python开发-Golang开发等 如果你正在寻找合适的工作，内推请联系我投递简历（E-Mail: eXVubGVpQHBpbmR1b2R1by5jb20=）

License

MIT

Copyright (c) 2018-present, @iChenLei