Flutter編碼規範及工具使用

最近學習聽課，講師講了下編碼規範及相對應對檢測工具講解，及自己的理解在這裏分享下。

命名規範

命名規範中包括了文件以及文件夾的命名規範，常量和變量的命名規範，類的命令規範。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) {
  }
}

註釋文檔生成

根據上面的代碼註釋內容，我們利用一個官方工具來將當前項目中的註釋轉化爲文檔。
打開命令行工具進入當前項目，或者在 Android Studio 點擊界面上的 Terminal 打開命令行窗口，運行如下命令。

dartdoc

運行結束後，會在當前項目目錄生成一個 doc 的文件夾。

在生成文件夾中，可以直接打開 doc/api/index.html 文件。

以上是使用標準的代碼註釋生成的文檔，利用這種方式將大大提升項目的可維護性，在項目初期就要做好此類規範。

庫引入規範

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 後，使用空格區分；

• 在 ( [ { } ] ) 符號後請勿使用空格；

• 在 { 後前使用空格；

• 使用 . 操作符，從第二個 . 符號後每次都使用新的一行。

• 其他規範可以參考 dartfmt 的官網。瞭解完以上規範後，我們現在將上面的 home_page.dart 進行修改，將部分代碼修改爲不按照上面規範的結構，代碼修改如下：

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) {
  }
}

上面 getCurrentTime 的參數和 { 沒有按照 dartfmt 規範來處理，在當前目錄下打開 Terminal，然後先運行以下命令來修復當前的代碼規範：

 dartfmt -w --fix lib/

{ 前無空格問題，和 getCurrentTime 參數空格問題，會被修復，說白了就是格式化代碼。

工具化

在 Dart 中同樣存在和 eslint 一樣的工具 dartanalyzer 來保證代碼質量（但是隻是靜態的檢測）。

該工具（ dartanalyzer ）已經集成在 Dart SDK ，你只需要在 Dart 項目根目錄下新增analysis_options.yaml 文件，然後在文件中按照規範填寫你需要執行的規則檢查即可，目前現有的檢查規則可以參考 Dart linter rules 規範。

爲了方便，我們可以使用現成已經配置好的規範模版，這裏有兩個庫 pedantic 和 effective_dart 可以參照使用。如果我們需要在項目中，使用它們兩者之一，可以在項目配置文件（ pubspec.yaml ）中新增如下兩行配置：

dependencies:
  flutter:
    sdk: flutter
  pedantic: ^1.9.2
  # 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.9.2

配置完成以後，在當前項目路徑下運行 flutter pub upgrade 。接下來在本地新增的 analysis_options.yaml 文件中新增如下配置：

include: package:pedantic/analysis_options.1.9.2.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

控制檯輸出

 lint • Document all public members. • lib/platform_view.dart:8:7 • public_member_api_docs

意思就是：需要添加註釋。

 lint • AVOID lines longer than 80 characters. • lib/simple_page_widgets.dart:81:1 • lines_longer_than_80_chars

意思是：每行超過了80字符，因爲我們的規範是80字符。

當然還會有其他問題，每個團隊都有自己對應的規則，根據自己匹配的規則進行修改。

總結，我們需要記住基礎規範及配置的規則和對應的命令。

基礎規範：規定基礎的代碼規範。
dartdoc :對代碼和註釋輸出文檔，這個很方便，只要註釋全，完全就是成品文檔，所以最開始就要養成良好註釋和編碼習慣。
dartfmt -w --fix lib/:美化、格式化lib下代碼。
dartanalyzer lib:根據編碼規範規則進行檢測修改lib下的代碼規範。前提需要配置`pubspec.yaml `和添加`analysis_options.yaml `.