Agile Alliance 京驿货车的Flutter编码规范-京东云开发者社区

#### 前言：
继京驿货车app减肥成功后，今天为大家带来了我们的flutter编码规范，下面，为大家详细介绍一下呦。

大家好，我们是京驿货车敏捷小组！ 项目里的很多代码，感觉命名规则/文件命名都不符合规范，每个人有自己的编码习惯和风格，会造成阅读难度大，代码逻辑难以理解，尤其在我们做双十一备战（代码ReView和逻辑梳理）的时候，上述问题尤为突出。

因为Flutter是2017年才发布的，很多同学都是从其他语言转向dart/flutter的，深感语言环境还需要大家共同去维护。建议还是规范化代码，这样可以增强可读性，提高编码效率和降低维护成本（快速定位问题等）。恰好dart语言官方有自己的代码规范和相关的说明在dartlang官网上，英文好的建议阅读原文，链接地址 https://dart.dev/guides/language/effective-dart/style

我们这里仅粗略翻译和加入一些自己的理解。

在我们看来，编码习惯都是因人而异的，并没有所谓的最佳方案。如果你是一个人开发，当然不需要在意这些问题，但是如果你的代码需要展现给别人，或者你需要与别人协同开发，编码规范就非常有必要了。

下面，将会从官方文档中选取最基本，最典型，发生率较高的一些情况，作为规范说明。
✅表示正面做法，❌表示反面做法

------------

#### 一、命名规范
##### 1.大驼峰
类、枚举、typedef和类型参数
![](//img1.jcloudcs.com/developer.jdcloud.com/53459d8f-0531-41be-a4e3-9a94022c3db520210119184426.png)

包括用于元数据注释的类
![](//img1.jcloudcs.com/developer.jdcloud.com/e7498e5c-0b13-4c83-8885-da64d037eba220210119184453.png)

##### 2.使用小写加下划线来命名库和源文件
![](//img1.jcloudcs.com/developer.jdcloud.com/f8b44926-9786-4910-8f1c-54538688b16320210119184522.png)
##### 3.使用小写加下划线来命名导入前缀 
![](//img1.jcloudcs.com/developer.jdcloud.com/8ad6916b-d55d-4199-8b7e-80d49368746c20210119184606.png)
##### 4.使用小驼峰法命名其他标识符
![](//img1.jcloudcs.com/developer.jdcloud.com/bc9dca1f-2c9e-436c-9939-46a0c0280e6720210119184629.png)
##### 5.优先使用小驼峰法作为常量命名
![](//img1.jcloudcs.com/developer.jdcloud.com/8a24d404-db72-4bac-8432-ac0e5abf535f20210119184653.png)
##### 6.不使用前缀字母
因为Dart可以告诉您声明的类型、范围、可变性和其他属性，所以没有理由将这些属性编码为标识符名称。  
![](//img1.jcloudcs.com/developer.jdcloud.com/955f617d-428b-4077-8837-680e70eb734b20210119184722.png)
#### 二、排序
为了使你的文件前言保持整洁，我们有规定的命令，指示应该出现在其中。每个“部分”应该用空行分隔。
##### 1.在其他引入之前引入所需的dart库
![](//img1.jcloudcs.com/developer.jdcloud.com/9f993d94-a67a-4671-ae03-9836f684187220210119185324.png)
##### 2.在相对引入之前先引入在包中的库
![](//img1.jcloudcs.com/developer.jdcloud.com/ab8325d8-4377-40be-b5bf-55790a3e9a1d20210119185353.png)
##### 3.第三方包的导入先于其他包
![](//img1.jcloudcs.com/developer.jdcloud.com/a4fdbb00-6ff8-458c-86c0-1ffc2fc63b8c20210119185421.png)
##### 4.在所有导入之后，在单独的部分中指定导出  
![](//img1.jcloudcs.com/developer.jdcloud.com/b84e3b30-63e4-4123-beaf-1417b78b464020210119185450.png)
#### 三、所有流控制结构，请使用大括号
##### 推荐：这样做可以避免悬浮的else问题
![](//img1.jcloudcs.com/developer.jdcloud.com/2a64e5af-a5bd-4ab0-99c2-362efdb188ab20210119185522.png)
##### 1.例外
一个if语句没有else子句，其中整个if语句和then主体都适合一行。在这种情况下，如果你喜欢的话，你可以去掉大括号 
![](//img1.jcloudcs.com/developer.jdcloud.com/0fd8f280-2a72-4def-af0d-e1ada043295020210119185551.png)
如果流程体超出了一行需要分划请使用大括号：
![](//img1.jcloudcs.com/developer.jdcloud.com/290a1179-409a-4ff0-88fa-2ea70433121320210119185615.png)
#### 四、注释规范
##### DO: 在dart的注释中，更加推荐使用///而非//
![](//img1.jcloudcs.com/developer.jdcloud.com/26983472-de34-40de-a1d7-67df7210367220210119185652.png)
至于为什么要这样做，官方表示是由于历史原因以及他们觉得这个在某些情况下看起来更方便阅读。
##### DO: 文档注释应该以一句简明的话开头
![](//img1.jcloudcs.com/developer.jdcloud.com/65181f89-0708-48bb-bb28-8d04df8cbfbd20210119185726.png)
##### DO: 将注释的第一句与其他内容分隔开来
![](//img1.jcloudcs.com/developer.jdcloud.com/1daf99d2-547f-4808-8dd5-17ca2290009220210119185757.png)
##### DO: 使用方括号去声明参数、返回值以及抛出的异常
![](//img1.jcloudcs.com/developer.jdcloud.com/193a5b6b-2ef5-46f4-8fdf-3cd8154c8ec920210119185827.png)
##### 文件头部注释（option,koroFileHeader for vscode）
![](//img1.jcloudcs.com/developer.jdcloud.com/f207b66d-a102-4dc3-a82c-97a9171e597f20210119185901.png)

#### 五、使用参考
##### 1.库的引用
flutter 中，导入lib下文件库，统一指定包名，避免过多的../../
![](//img1.jcloudcs.com/developer.jdcloud.com/36994322-e765-4662-ad97-a9a99b59339e20210119185948.png)
##### 2.字符串的使用
**(1)使用相邻字符串连接字符串文字**
如果有两个字符串字面值(不是值，而是实际引用的字面值)，则不需要使用+连接它们。就像在C和c++中，简单地把它们放在一起就能做到。这是创建一个长字符串很好的方法但是不适用于单独一行。
![](//img1.jcloudcs.com/developer.jdcloud.com/49a93ca1-ac71-4214-90db-aaf4d4d85f5320210119190016.png)

**(2)优先使用模板字符串**
![](//img1.jcloudcs.com/developer.jdcloud.com/1da71ffa-5b40-4c2d-96db-ca4ffcd8ad6020210119190101.png)

**(3)在不需要的时候，避免使用花括号**
![](//img1.jcloudcs.com/developer.jdcloud.com/009f1dde-7ea8-4c1a-aa57-bbd43f547e8b20210119190145.png)
##### 3.集合
**(1)尽可能使用集合字面量**
如果要创建一个不可增长的列表，或者其他一些自定义集合类型，那么无论如何，都要使用构造函数。
![](//img1.jcloudcs.com/developer.jdcloud.com/480f7ac7-2514-4e51-bd0b-bd28628e3cda20210119190220.png)

**(2)不要使用.length查看集合是否为空**
![](//img1.jcloudcs.com/developer.jdcloud.com/06e39b2a-7c39-4add-b25e-4e03f2a57c9020210119190249.png)

**(3)考虑使用高阶方法转换序列**
如果有一个集合，并且希望从中生成一个新的修改后的集合，那么使用.map()、.where()和Iterable上的其他方便的方法通常更短，也更具有声明性
![](//img1.jcloudcs.com/developer.jdcloud.com/adbe7f07-7d5b-4383-9162-eac3de9b8af820210119190320.png)

**(4)避免使用带有函数字面量的Iterable.forEach()**
在Dart中，如果你想遍历一个序列，惯用的方法是使用循环。
![](//img1.jcloudcs.com/developer.jdcloud.com/342876d5-7a92-4f37-bf30-77241acb4bda20210119190347.png)

**(5)不要使用List.from()，除非打算更改结果的类型**
给定一个迭代，有两种明显的方法可以生成包含相同元素的新列表
![](//img1.jcloudcs.com/developer.jdcloud.com/2f57dca9-0ebf-4e6a-be40-337b10547f7120210119190526.png)

明显的区别是第一个比较短。重要的区别是第一个保留了原始对象的类型参数
![](//img1.jcloudcs.com/developer.jdcloud.com/c6ff1825-b32c-402c-9ffb-6518128d1b2c20210119190555.png)

##### 4.参数的使用
**使用=将命名参数与其默认值分割开**
由于遗留原因，Dart均允许“:”和“=”作为指定参数的默认值分隔符。为了与可选的位置参数保持一致，使用“=”。  
![](//img1.jcloudcs.com/developer.jdcloud.com/c6b048b6-843b-4a8a-abad-8e7a3c33749320210119190625.png)
**
不要使用显式默认值null**
如果参数是可选的，但没有给它一个默认值，则语言隐式地使用null作为默认值，因此不需要编写它
![](//img1.jcloudcs.com/developer.jdcloud.com/23e68c5a-ddea-431f-a41b-7a3916ba810420210119190659.png)

##### 5.变量
**(1)不要显式地将变量初始化为空**
在Dart中，未显式初始化的变量或字段自动被初始化为null。不要多余赋值null 
![](//img1.jcloudcs.com/developer.jdcloud.com/24383b14-ac42-477f-a1c8-327027fcf8dd20210119190733.png)

**(2)避免储存你能计算的东西**
在设计类时，您通常希望将多个视图公开到相同的底层状态。通常你会看到在构造函数中计算所有视图的代码，然后存储它们:
![](//img1.jcloudcs.com/developer.jdcloud.com/e70e8b82-a244-46d0-ae30-a6160e92996020210119190802.png)

**如上代码问题：**
a，浪费内存
b，缓存的问题是无效——如何知道何时缓存过期需要重新计算？  
![](//img1.jcloudcs.com/developer.jdcloud.com/e1f7a04b-d726-48b5-8231-15d9f9f727f920210119190831.png)

##### 6.类成员
const 宏 final
**优先使用final字段来创建只读属性**
尤其对于 StatelessWidget
在不需要的时候不要用this
![](//img1.jcloudcs.com/developer.jdcloud.com/e902ebcd-21ba-4223-a070-5b3b52281e2620210119190923.png)
##### 7.构造函数
尽可能使用初始化的形式
![](//img1.jcloudcs.com/developer.jdcloud.com/373fb015-761c-464b-b6ea-70bc3e5e03b020210119190954.png)

##### 8.不要使用new
Dart2使new 关键字可选
![](//img1.jcloudcs.com/developer.jdcloud.com/c8885f1e-c86c-4b06-b170-8a097907d9a320210119191023.png)

##### 9.异步
优先使用async/await代替原始的futures
async/await语法提高了可读性，允许你在异步代码中使用所有Dart控制流结构。  
![](//img1.jcloudcs.com/developer.jdcloud.com/4f6bdff0-ce0e-42e7-9e28-d6be2dd4a13720210119191054.png)

**当异步没有任何用处时，不要使用它**
如果可以在不改变函数行为的情况下省略异步，那么就这样做。 
![](//img1.jcloudcs.com/developer.jdcloud.com/91da8935-23ef-444e-a878-96a0d409021320210119191123.png)

------------

###### Being Agile 京东物流技术发展部效能提升部
###### 作者：快递技术部 曹忆鹏