在实践编程之前,我们先来掌握代码规范,毕竟优秀的编程代码从规范开始。
命名规范
命名规范中包括了文件以及文件夹的命名规范,常量和变量的命名规范,类的命令规范。Dart 中只包含这三种命名标识。
-
AaBb 类规范,首字母大写驼峰命名法,例如 IsClassName,常用于类的命名。
-
aaBb 类规范,首字母小写驼峰命名法,例如 isParameterName,常用于常量以及变量命名。
-
aa_bb 类规范,小写字母下划线连接法,例如 is_a_flutter_file_name,常用于文件及文件夹命名。
注释规范
注释的目的是生成我们需要的文档,从而增强项目的可维护性。
单行注释
单行注释主要是“ // ”这类标示的注释方法,这类注释与其他各类语言使用的规范一致。单行注释主要对于单行代码逻辑进行解释,为了避免过多注释,主要是在一些理解较为复杂的代码逻辑上进行注释。
比如,下面这段代码没有注释,虽然你看上下文也会知道这里表示的是二元一次方程的 ∆ ,但是却不知道如果 ∆ 大于 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;
}
虽然单行注释大家都比较了解,但我这里还是多解释了下如何应用,主要是希望大家规范化使用,减少不必要的代码注释。
多行注释
在 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<HomePage> {
/// 获取当前时间戳
///
/// [prefix]需要传入一个前缀信息
/// 返回一个字符串类型的前缀信息:时间戳
String getCurrentTime(String prefix) {
}
/// 有状态类返回组件信息
@override
Widget build(BuildContext context) {
}
}
注释文档生成
根据上面的代码注释内容,我们利用一个官方工具来将当前项