5.Flutter Code Specification

Flutter由于上手难度低，性能体验好，特别大厂的力推，加速了它发展的脚步。
此系列文章仅用于自己学习，参考链接在文章结尾
在实践编程之前，我们先来掌握代码规范，毕竟优秀的编程代码从规范开始。

命名规范

命名规范中包括了文件以及文件夹的命名规范，常量和变量的命名规范，类的命令规范。Dart 中只包含这三种命名标识。

• AaBb 类规范，首字母大写驼峰命名法，例如 IsClassName，常用于类的命名。
• aaBb 类规范，首字母小写驼峰命名法，例如 isParameterName，常用于常量以及变量命名。
• aa_bb 类规范，小写字母下划线连接法，例如 is_a_flutter_file_name，常用于文件及文件夹命名。

注释规范

注释的目的是生成我们需要的文档，从而增强项目的可维护性。

1.单行注释

单行注释主要是“ // ”这类标示的注释方法，这类注释与其他各类语言使用的规范一致。单行注释主要对于单行代码逻辑进行解释，为了避免过多注释，主要是在一些理解较为复杂的代码逻辑上进行注释。

比如，下面这段代码没有注释，虽然你看上下文也会知道这里表示的是二元一次方程的 ∆ ，但是却不知道如果 ∆ 大于 0 ，为什么 x 会等于 2。

if ( b * b - 4 * a * c > 0 ) {
  x = 2;
}

如果加上注释则显得逻辑清晰容易理解，修改后如下所示。

// 当∆大于0则表示方程x个解，x则为2
if ( b * b - 4 * a * c > 0 ) {
  x = 2;
}

虽然单行注释大家都比较了解，但我这里还是多解释了下如何应用，主要是希望大家规范化使用，减少不必要的代码注释。

2.多行注释

在 Dart 中由于历史原因（前后对多行注释方式进行了修改）有两种注释方式，一种是 /// ，另外一种则是 / ...... / 或者 /....../ ，这两种都可以使用。/....../ 和 /....../ 这种块级注释方式在其他语言（比如 JavaScript ）中是比较常用的，但是在 Dart 中我们更倾向于使用 /// ，后续我们所有的代码都按照这个规范来注释。

多行注释涉及类的注释和函数的注释。两者在注释方法上一致。首先是用一句话来解释该类或者函数的作用，其次使用空行将注释和详细注释进行分离，在空行后进行详细的说明。如果是类，在详细注释中，补充该类作用，其次应该介绍返回出去的对象功能，或者该类的核心方法。如果是函数，则在详细注释中，补充函数中的参数以及返回的数据对象。

假设有一个 App 首页的库文件，其中包含类 HomePage ， HomePage 中包含两个方法，一个是 getCurrentTime ，另一个是 build 方法，代码注释如下（未实现其他部分代码）。

import 'package:flutter/material.dart';
/// APP 首页入口
/// 
/// 本模块函数，加载状态类组件HomePageState
class HomePage extends StatefulWidget {
  @override
  createState() => new HomePageState();
}
/// 首页有状态组件类
///
/// 主要是获取当前时间，并动态展示当前时间
class HomePageState extends State {
  /// 获取当前时间戳
  ///
  /// [prefix]需要传入一个前缀信息
  /// 返回一个字符串类型的前缀信息：时间戳
  String getCurrentTime(String prefix) {
  }
  /// 有状态类返回组件信息
  @override
  Widget build(BuildContext context) {
  }
}

库引入规范

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';

代码美化

1.dartfmt

在 Dart 中同样有和前端一样的工具 pritter ，在 Dart 中叫作 dartfmt ，该工具已经包含在 Dart SDK 中，因此可以直接运行如下命令检查是否生效。

dartfmt -h

dartfmt 工具的规范包括了以下几点：

• 使用空格而不是 tab；
• 在一个完整的代码逻辑后面使用空行区分；
• 二元或者三元运算符之间使用空格；
• 在关键词 , 和 ; 之后使用空格；
• 一元运算符后请勿使用空格；
• 在流控制关键词，例如 for 和 while 后，使用空格区分；
• 在 ( [ { } ] ) 符号后请勿使用空格；
• 在 { 后前使用空格；
• 使用 . 操作符，从第二个 . 符号后每次都使用新的一行。

在当前目录下打开 Terminal，然后运行以下命令来修复当前的代码规范：

 dartfmt -w --fix lib/

2.在Android Studio中自动格式化代码

要在当前源代码窗口中自动格式化代码，请右键单击代码窗口并选择Reformat code with dartfmt。您也可以通过快捷键“option+command+L”来格式化代码。

image.png

工具化

上面介绍了这些规范，在 Dart 中同样存在和 eslint 一样的工具 dartanalyzer 来保证代码质量。该工具（ dartanalyzer ）已经集成在 Dart SDK ，你只需要在 Dart 项目根目录下新增analysis_options.yaml 文件，然后在文件中按照规范填写你需要执行的规则检查即可，目前现有的检查规则可以参考 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
    # 对于常量名，最好使用小写。
    - constant_identifier_names # prefer
    # 避免超过80个字符的行
    - lines_longer_than_80_chars # avoid
    # 公共的api要写注释
    - package_api_docs # prefer
    # 公共的变量要写注释
    - public_member_api_docs # prefer

增加完成以上配置后，运行如下命令可进行检查。

dartanalyzer lib

运行完成以后，你可以看到一些提示、警告或者报错信息，具体提示如图

image.png

• 没有为 main 类中的 public 方法增加文档说明；
• 在 main 类中 import 了developer 库，但是未使用；
• 在 main 类中 import 了 home_page.dart 库，但是未使用；
• 在 home_page.dart 中的 getCurrentTime 使用了 String 返回类型，但是未返回相应类型；
• 在 home_page.dart 中的 build 方法 使用了 Widaget 返回类型，但是未返回相应类型

这些问题非常清晰地说明了我们目前代码存在的问题，有了以上工具化的校验检查，我们在做团队代码规范的时候，就非常简单。

学习地址：

Flutter中文网

Flutter实战

闲鱼技术社区

掘金Flutter社区

拉勾教育