Flutter 代码规范
命名规范
命名规范中包括了文件以及文件夹的命名规范,常量和变量的命名规范,类的命令规范。Dart 中只包含这三种命名标识。
AaBb 类规范
,首字母大写驼峰命名法,例如IsClassName
,常用于类的命名
。
aaBb 类规范
,首字母小写驼峰命名法,例如isParameterName
,常用于常量
以及变量命名
。
aa_bb 类规范
,小写字母下划线连接法,例如is_a_flutter_file_name
,常用于文件
及文件夹命名
。
注释规范
注释的目的是生成我们需要的文档,从而增强项目的可维护性。
单行注释
单行注释
主要是 //
这类标示的注释方法,这类注释与其他各类语言使用的规范一致。单行注释主要对于单行代码逻辑进行解释
,为了避免过多注释,主要是在一些理解较为复杂的代码逻辑上进行注释
。
多行注释
在 Dart 中由于历史原因(前后对多行注释方式进行了修改)有两种注释方式,一种是 ///
,另外一种则是 / **......* /
或者 /*......*/
,这两种都可以使用。/**......*/
和 /*......*/
这种块级注释方式在其他语言(比如 JavaScript )中是比较常用的,但是在 Dart 中我们更倾向于使用 ///
多行注释涉及类的注释和函数的注释。两者在注释方法上一致。首先是用一句话来解释该类或者函数的作用
,其次使用空行将注释和详细注释进行分离,在空行后进行详细的说明
。如果是类,在详细注释中,补充该类作用,其次应该介绍返回出去的对象功能,或者该类的核心方法。如果是函数,则在详细注释中,补充函数中的参数以及返回的数据对象。
注释文档生成
根据代码注释内容,我们可以利用一个官方工具 dartdoc 命令
来将当前项目中的注释转化为文档。该工具的执行命令在 Dart 执行命令的同一个目录下
打开命令行工具进入当前项目,或者在 Android Studio 点击界面上的 Terminal 打开命令行窗口,运行如下命令
dartdoc
运行结束后,会在当前项目目录生成一个 doc 的文件夹。在生成文件夹中,可以直接打开 doc/api/index.html
文件
若报错:
dartdoc failed: Top level package requires Flutter but FLUTTER_ROOT environment variable not set.
需要配置 FLUTTER_ROOT
环境变量,可查看 Mac 搭建 Flutter 开发环境
export FLUTTER_ROOT=你的 flutter 安装目录
库引入规范
Dart 为了保持代码的整洁,规范了 import 库的顺序。将 import 库分为了几个部分,每个部分使用空行分割。分为 dart 库、package 库和其他的未带协议头(例如下面中的 util.dart )的库。其次相同部分按照模块的首字母的顺序来排列,例如下面的代码示例:
import 'dart:developer';
import 'package:flutter/material.dart';
import 'package:two_you_friend/pages/home_page.dart';
import 'util.dart';
代码美化
在 Dart 中同样有和前端一样的工具 pritter ,在 Dart 中叫作 dartfmt
,该工具和 dartdoc 一样,已经包含在 Dart SDK 中,因此可以直接运行如下命令检查是否生效:
dartfmt -h
dartfmt
dartfmt 工具的规范包括了以下几点:
使用空格而不是 tab;
在一个完整的代码逻辑后面使用空行区分;
二元或者三元运算符之间使用空格;
在关键词 , 和 ; 之后使用空格;
一元运算符后请勿使用空格;
在流控制关键词,例如 for 和 while 后,使用空格区分;
在 ( [ { } ] ) 符号后请勿使用空格;
在 { 后前使用空格;
使用 . 操作符,从第二个 . 符号后每次都使用新的一行。
打开命令行工具进入当前项目,或者在 Android Studio 点击界面上的 Terminal 打开命令行窗口,运行如下命令来格式化代码规范
dartfmt -w --fix lib/
在 Android Studio 和 IntelliJ 中自动格式化代码
要在当前源代码窗口中自动格式化代码,请右键单击代码窗口并选择
Reformat code with dartfmt
。你也可以通过快捷键来格式化代码
工具化
上面介绍了这些规范,在 Dart 中同样存在和 eslint 一样的工具 dartanalyzer
来保证代码质量。
该工具 dartanalyzer 已经集成在 Dart SDK
,你只需要在 Dart 项目根目录下新增 analysis_options.yaml
文件,然后在文件中按照规范填写你需要执行的规则检查即可,目前现有的检查规则可以参考 Dart linter rules 规范。
为了方便,我们可以使用现成已经配置好的规范模版,这里有两个库 pedantic
和 effective_dart
可以参照使用。如果我们需要在项目中,使用它们两者之一,可以在项目配置文件 pubspec.yaml
中新增如下两行配置:
dependencies:
flutter:
sdk: flutter
pedantic: ^1.8.0
# The following adds the Cupertino Icons font to your application.
# Use with the CupertinoIcons class for iOS style icons.
cupertino_icons: ^0.1.2
dev_dependencies:
flutter_test:
sdk: flutter
pedantic: ^1.8.0
配置完成以后,在当前项目路径下运行 flutter pub upgrade
。接下来在本地新增的 analysis_options.yaml
文件中新增如下配置:
include: package:pedantic/analysis_options.1.8.0.yaml
如果我们认为 pedantic
不满足我们的要求,我们再根据 Dart linter rules 规范
,前往选择自己需要的规范配置,修改下面的配置:
include: package:pedantic/analysis_options.1.8.0.yaml
analyzer:
strong-mode:
implicit-casts: false
linter:
rules:
# STYLE
- camel_case_types
- camel_case_extensions
- file_names
- non_constant_identifier_names
- constant_identifier_names # prefer
- directives_ordering
- lines_longer_than_80_chars # avoid
# DOCUMENTATION
- package_api_docs # prefer
- public_member_api_docs # prefer
我在 pedantic
的基础上又增加了一些对于样式和文档的规范,增加完成以上配置后,运行如下命令可进行检查。
dartanalyzer lib
运行完成以后,你可以看到一些提示、警告或者报错信息
有了以上工具化的校验检查,我们在做团队代码规范的时候,就非常简单。
通过学习 Flutter 快学快用 24 讲
之 04 | 代码规范:实践开发 Flutter 编程代码规范工具
进行整理记录