dart/flutter 代码规范
（一）高效 Dart 语言指南
风格指南
1.1、如何写注释
推荐 简洁，保持一致.
避免 缩写和首字母缩写词，除非很常见。
推荐 使用 “this” 而不是 “the” 来引用实例成员。
要像句子一样来格式化注释，不要使用块注释作用作解释说明。
要 使用 /// 文档注释来注释成员和类型，使用文档注释可以让 [dartdoc][] 来为你生成代码 API 文档。
推荐 为公开发布的 API 编写文档注释。
考虑 编写库级别（library-level）的文档注释。
-
关于库用途的单句摘要。
-
解释库中用到的术语。
-
一些配合 API 的示例代码。
-
最重要和最常用的类和函数的链接。
-
和库相关领域的外部链接。
推荐 为私有API 编写文档注释。
要在文档注释开头有一个单句总结。
要 让文档注释的第一句从段落中分开，即自成一段，突出
避免 与周围上下文冗余。
推荐 用第三人称来开始函数或者方法的文档注释。
注释应该关注于代码 所实现的 功能。
推荐 使用名词短语来为非布尔值变量或属性注释。
推荐 使用名词短语来开始库和类型注释。
考虑 在文档注释中添加示例代码。
要 使用方括号在文档注释中引用作用域内的标识符
/// Throws a [StateError] if ...
/// similar to [anotherMethod()], but ...要 使用平白简单的语句来描述参数、返回值以及异常信息。
要 把注释文档放到注解之前。
文档注释中允许使用大多数 markdown 格式，并且 dartdoc 会根据 markdown package. 进行解析。
避免 过度使用 markdown。
避免 使用 HTML 来格式化文字。
推荐 使用反引号标注代码。
反引号语法避免了那些缩进的问题，而且能够指出代码的语言类型，内联代码同样可以使用反引号标注。
（二）https://www.jianshu.com/p/047eb78dce53
文章首发地址: https://www.jianshu.com/p/047eb78dce53
前言
最近看qq群里发的很多代码截图,感觉命名规则/文件命名都不符合规范
很多朋友都是从其他语言转向dart/flutter的,深感语言环境还需要大家共同去维护,建议还是规范化代码,这样所有人看着都会舒服
恰好dart语言官方有自己的代码规范和相关的说明,在dartlang官网上,英文好的建议阅读原文
连接地址 https://www.dartlang.org/guides/language/effective-dart/style
我这里仅粗略翻译和加入一些自己的理解
图片均来自于上述url对应的页面中
当前dart版本为2.0版本,日期为2018年08月22日
可能会在未来有改动,到时请以最新文档为准
文档中图片的绿色部分为正例,右上角带good标识
红色是反例,右上角带bad标识
标识方案
在dart有3种常规标识方案
第一个为大写字母开头的驼峰式 如 UserInterface 每个词的首字母为大写
第二个是小写开头的驼峰式,如testRun,第一个单词是小写,后续每个单词首字母大写
第三个是每个单词均为小写,以下划线分隔,如user_response
总结
如果不想往下看具体的图片和翻译,直接看这里
文件名: 小写+下划线
类型名(类名,函数类型名):大写开头驼峰
变量名(包含const final 常量):使用小写开头驼峰, 项目有特殊要求 const可以使用大写+下划线的方式,如同java中一样
导包as后的名称为小写+下划线
不要用匈牙利命名法中的kXXXX 这样的命名方式,应该去掉k
超过两位的英文缩写一律按该单词为普通小写单词处理,使用小写
导包有顺序要求,且每"部分"间空行分隔开,每部分内按字母排序,按如下顺序排序
dart sdk内的库
flutter内的库
第三方库
自己的库
相对路径引用
先全部import再export,不要交替进行
使用dartfmt工具格式化dart文件代码 dartfmt -w lib/ flutter可以用flutter format lib
单行字符建议不要超过80个
流程控制语句无论如何都使用花括号包裹,即使只有单行
格式化个人建议:
建议不要使用idea/as/vscode 的自动储存格式化作为交付
因为idea/vs有自己的格式化工具,并不是使用的dartfmt,这样会造成代码交付格式不统一,写代码过程中可以使用以方便提高阅读性,但每次代码commit前建议使用 dartfmt -w lib/ 来格式化代码,以便于项目代码风格的统一,flutter用户使用 flutter format lib
类型名称
适用于类名,注解名,typedef定义的函数名
这里有一个特例,当你的注解是一个const的常量时,使用@foo的方式作为注解
库名称,文件名用小写+下划线
使用小写+下划线方式命名library,文件名
原因如下:
某些文件系统不区分大小写，因此许多项目要求文件名全部为小写。使用分隔字符允许名称仍以该形式可读。使用下划线作为分隔符可确保名称仍然是有效的Dart标识符
导入时
当导入包时, 如果涉及到as, 一律使用小写+下划线方式
其他标识符
包含顶级成员,类成员,方法内成员,参数名,命名参数名,一律使用小写驼峰式
常量名称
建议使用小写驼峰式命名
但是你的项目中如果使用大写+下划线分割单词的方式,则可以继续使用这种方式
这里有个小说明:最初dart中采用的大写+下划线方式,但是后来有一些变量需要修改为非const变量,就需要修改为小写驼峰式,后一律使用小写驼峰式
缩写相关
超过两位的使用常规方式,两位以内使用大写
在小写驼峰式中,会出现一些约定俗成的缩写,如http ftp io等,这些在英文词法中都应该是大写,但大写连续会破坏可读性,如HTTPSFTP,你不知道是HTTPS FTP 还是 HTTP SFTP,所以采用如上图绿色的方式来命名
不要使用前缀字母
匈牙利命名法中使用缩写开头的小写驼峰命名法时,是因为当时编辑器无法很好帮助理解你的代码,这样命名法能够很好的帮助你去理解代码,现在dart语言中,编辑器可以很好的通过声明等方式帮你理解你的代码,故,不要使用前缀字母,如上图绿色
规定代码的顺序
为了使文件保持整洁，我们有一个规定代码顺序。每个“部分”应该用空行分隔。
保证dart的导入顺序在所有其他包之前
保证带包名的引用方式在相对路径引用之前
首先import第三方的包
导入自己的包在后面一个单独的部分
全部导入完毕后,再export 导出
每个部分按字母顺序排序
格式化
使用dartfmt 程序来格式化代码
单行长度为80字符
可读性研究表明，长行文字难以阅读，因为当你移动到下一行的开头时，你的眼睛必须走得更远。这就是报纸和杂志使用多列文本的原因。
如果你真的发现自己想要超过80个字符的行，我们的经验是你的代码可能过于冗长而且可能更紧凑。主要罪犯通常是VeryLongCamelCaseClassNames。问问自己，“该类型名称中的每个单词是否告诉我一些关键或防止名称冲突？”如果不是，请考虑省略它。
流程控制使用花括号
浙公网安备 33010602011771号