學習Flutter，你需要了解的Dart 編碼規範

安卓小哥發表於2019-08-02

FlutterDart

本文來自dart官方文件中的【Effective Dart】

規範主要分為四個部分：

樣式規範
文件規範
使用規範
設計規範

每個部分都有許多的例子說明，每個例子都會以下面五個詞中的某些作為開頭：

DO ：表示你需要遵守的做法
DONT ：表示這樣的做法是非常不好的
PREFER ：在多數情況下，都推薦的做法
AVOID ：在多數情況下，都應該避免的做法
CONSIDER ：需要你自己去斟酌的做法

在我看來，編碼習慣都是因人而異的，並沒有所謂的最佳方案。

如果你是一個人開發，當然不需要在意這些問題，但是如果你的程式碼需要展現給別人，或者你需要與別人協同開發，編碼規範就非常有必要了。

下面，將會從官方文件中選取最基本，最典型，發生率較高的一些情況，作為規範說明。

✅表示正面做法，❌表示反面做法

樣式規範

命名

DO: 類, 列舉, 型別定義, 以及泛型，都需要使用大寫開頭的駝峰命名法

✅
class SliderMenu { ... }

class HttpRequest { ... }

typedef Predicate<T> = bool Function(T value);
複製程式碼

在使用註解時候，也應該這樣

✅

class Foo {
  const Foo([arg]);
}

@Foo(anArg)
class A { ... }

@Foo()
class B { ... }
複製程式碼

不過為一個類的建構函式新增註解時，你可能需要建立一個小寫開頭的註解變數

✅

const foo = Foo();

@foo
class C { ... }
複製程式碼

DO: 命名庫、包、目錄、dart檔案都應該是小寫加上下劃線

✅

library peg_parser.source_scanner;

import 'file_system.dart';
import 'slider_menu.dart';
複製程式碼

❌

library pegparser.SourceScanner;

import 'file-system.dart';
import 'SliderMenu.dart';
複製程式碼

DO: 將引用使用as轉換的名字也應該是小寫下劃線

✅

import 'dart:math' as math;
import 'package:angular_components/angular_components'
    as angular_components;
import 'package:js/js.dart' as js;
複製程式碼

❌

import 'dart:math' as Math;
import 'package:angular_components/angular_components'
    as angularComponents;
import 'package:js/js.dart' as JS;
複製程式碼

DO: 變數名、方法、引數名都應該是小寫開頭的駝峰命名法

✅

var item;

HttpRequest httpRequest;

void align(bool clearItems) {
  // ...
}
複製程式碼

✅

const pi = 3.14;
const defaultTimeout = 1000;
final urlScheme = RegExp('^([a-z]+):');

class Dice {
  static final numberGenerator = Random();
}
複製程式碼

❌

const PI = 3.14;
const DefaultTimeout = 1000;
final URL_SCHEME = RegExp('^([a-z]+):');

class Dice {
  static final NUMBER_GENERATOR = Random();
}

複製程式碼

花括號

DO: 只有一個if語句且沒有else的時候，並且在一行內能夠很好的展示，就可以不用花括號

✅

if (arg == null) return defaultValue;
複製程式碼

但是如果一行內展示比較勉強的話，就需要用花括號了：

✅

if (overflowChars != other.overflowChars) {
  return overflowChars < other.overflowChars;
}
複製程式碼

❌

if (overflowChars != other.overflowChars)
  return overflowChars < other.overflowChars;
複製程式碼

文件規範

DO: 在dart的註釋中，更加推薦使用///而非//

✅

/// The number of characters in this chunk when unsplit.
int get length => ...
複製程式碼

❌

// The number of characters in this chunk when unsplit.
int get length => ...
複製程式碼

至於為什麼要這樣做，官方表示是由於歷史原因以及他們覺得這個在某些情況下看起來更方便閱讀。

DO: 文件註釋應該以一句簡明的話開頭

✅

/// Deletes the file at [path] from the file system.
void delete(String path) {
  ...
}
複製程式碼

❌

/// Depending on the state of the file system and the user's permissions,
/// certain operations may or may not be possible. If there is no file at
/// [path] or it can't be accessed, this function throws either [IOError]
/// or [PermissionError], respectively. Otherwise, this deletes the file.
void delete(String path) {
  ...
}
複製程式碼

DO: 將註釋的第一句與其他內容分隔開來

✅

/// Deletes the file at [path].
///
/// Throws an [IOError] if the file could not be found. Throws a
/// [PermissionError] if the file is present but could not be deleted.
void delete(String path) {
  ...
}
複製程式碼

❌

/// Deletes the file at [path]. Throws an [IOError] if the file could not
/// be found. Throws a [PermissionError] if the file is present but could
/// not be deleted.
void delete(String path) {
  ...
}
複製程式碼

DO: 使用方括號去宣告引數、返回值以及丟擲的異常

❌

/// Defines a flag with the given name and abbreviation.
///
/// @param name The name of the flag.
/// @param abbr The abbreviation for the flag.
/// @returns The new flag.
/// @throws ArgumentError If there is already an option with
///     the given name or abbreviation.
Flag addFlag(String name, String abbr) => ...
複製程式碼

✅

/// Defines a flag.
///
/// Throws an [ArgumentError] if there is already an option named [name] or
/// there is already an option using abbreviation [abbr]. Returns the new flag.
Flag addFlag(String name, String abbr) => ...
複製程式碼

使用規範

依賴

PREFER: 推薦使用相對路徑匯入依賴

如果專案結構如下：

my_package
└─ lib
   ├─ src
   │  └─ utils.dart
   └─ api.dart
複製程式碼

想要在 api.dart 中匯入 utils.dart

✅

import 'src/utils.dart';
複製程式碼

❌

import 'package:my_package/src/utils.dart';
複製程式碼

賦值

DO: 使用??將null值做一個轉換

在dart中 ?? 操作符表示當一個值為空時會給它賦值 ?? 後面的資料

❌

if (optionalThing?.isEnabled) {
  print("Have enabled thing.");
}
複製程式碼

當 optionalThing 為空的時候，上面就會有空指標異常了。

這裡說明一下。 ?. 操作符相當於做了一次判空操作，只有當 optionalThing 不為空的時候才會呼叫 isEnabled 引數，當 optionalThing 為空的話預設返回null，用在if判斷句中自然就不行了

下面是正確做法

✅

// 如果為空的時候你想返回false的話:
optionalThing?.isEnabled ?? false;

// 如果為空的時候你想返回ture的話:
optionalThing?.isEnabled ?? true;
複製程式碼

❌

optionalThing?.isEnabled == true;

optionalThing?.isEnabled == false;
複製程式碼

字串

在dart中，不推薦使用 + 去連線兩個字串

DO: 使用Enter鍵直接分隔字串

✅

raiseAlarm(
    'ERROR: Parts of the spaceship are on fire. Other '
    'parts are overrun by martians. Unclear which are which.');
複製程式碼

❌

raiseAlarm('ERROR: Parts of the spaceship are on fire. Other ' +
    'parts are overrun by martians. Unclear which are which.');
複製程式碼

PREFER: 使用${}來連線字串與變數值

✅

'Hello, $name! You are ${year - birth} years old.';
複製程式碼

❌

'Hello, ' + name + '! You are ' + (year - birth).toString() + ' y...';
複製程式碼

集合

dart中建立空的可擴充套件 List 有兩種方法: [] 和 List();建立空的 HashMap 有三種方法: {}, Map(),和 LinkedHashMap()

如果要建立不可擴充套件的列表或其他一些自定義集合型別，那麼務必使用建構函式。

DO: 儘可能使用簡單的字面量建立集合

✅

var points = [];
var addresses = {};
複製程式碼

❌

var points = List();
var addresses = Map();
複製程式碼

當你想要指定型別的時候

✅

var points = <Point>[];
var addresses = <String, Address>{};
複製程式碼

❌

var points = List<Point>();
var addresses = Map<String, Address>();
複製程式碼

DON’T: 不要使用.lenght的方法去表示一個集合是空的

✅

if (lunchBox.isEmpty) return 'so hungry...';
if (words.isNotEmpty) return words.join(' ');
複製程式碼

❌

if (lunchBox.length == 0) return 'so hungry...';
if (!words.isEmpty) return words.join(' ');
複製程式碼

CONSIDER: 考慮使用高階方法轉換序列

var aquaticNames = animals
    .where((animal) => animal.isAquatic)
    .map((animal) => animal.name);
複製程式碼

AVOID: 避免使用帶有函式字面量的Iterable.forEach()

forEach（）函式在JavaScript中被廣泛使用，因為內建的for-in迴圈不能達到你通常想要的效果。在Dart中，如果要迭代序列，那麼慣用的方法就是使用迴圈。

✅

for (var person in people) {
  ...
}
複製程式碼

❌

people.forEach((person) {
  ...
});
複製程式碼

DON’T: 不要使用 List.from() 除非你打算更改結果的型別

有兩種方法去獲取 Iterable，分別是List.from()和Iterable.toList()

✅

// 建立一個List<int>:
var iterable = [1, 2, 3];

// 輸出"List<int>":
print(iterable.toList().runtimeType);
複製程式碼

❌

// 建立一個List<int>:
var iterable = [1, 2, 3];

// 輸出"List<dynamic>":
print(List.from(iterable).runtimeType);
複製程式碼

DO: 使用 whereType()去用型別過濾一個集合

❌

var objects = [1, "a", 2, "b", 3];
var ints = objects.where((e) => e is int);
複製程式碼

❌

var objects = [1, "a", 2, "b", 3];
var ints = objects.where((e) => e is int).cast<int>();

複製程式碼

✅

var objects = [1, "a", 2, "b", 3];
var ints = objects.whereType<int>();
複製程式碼

引數

DO: 使用 = 給引數設定預設值

✅

void insert(Object item, {int at = 0}) { ... }
複製程式碼

❌

void insert(Object item, {int at: 0}) { ... }
複製程式碼

DON’T: 不要將引數的預設值設定為 null

✅

void error([String message]) {
  stderr.write(message ?? '\n');
}
複製程式碼

❌

void error([String message = null]) {
  stderr.write(message ?? '\n');
}
複製程式碼

變數

AVOID: 避免儲存可以計算的值

❌

class Circle {
  num _radius;
  num get radius => _radius;
  set radius(num value) {
    _radius = value;
    _recalculate();
  }

  num _area;
  num get area => _area;

  num _circumference;
  num get circumference => _circumference;

  Circle(this._radius) {
    _recalculate();
  }

  void _recalculate() {
    _area = pi * _radius * _radius;
    _circumference = pi * 2.0 * _radius;
  }
}
複製程式碼

✅

class Circle {
  num radius;

  Circle(this.radius);

  num get area => pi * radius * radius;
  num get circumference => pi * 2.0 * radius;
}
複製程式碼

成員

DON’T: 不要寫沒必要的getter 和 setter

✅

class Box {
  var contents;
}
複製程式碼

❌

class Box {
  var _contents;
  get contents => _contents;
  set contents(value) {
    _contents = value;
  }
}
複製程式碼

建構函式

DO: 儘可能使用簡單的初始化形式

❌

class Point {
  num x, y;
  Point(num x, num y) {
    this.x = x;
    this.y = y;
  }
}
複製程式碼

✅

class Point {
  num x, y;
  Point(this.x, this.y);
}
複製程式碼

DON’T: 不要使用 new 來建立物件

dart中不需要new

✅

Widget build(BuildContext context) {
  return Row(
    children: [
      RaisedButton(
        child: Text('Increment'),
      ),
      Text('Click!'),
    ],
  );
}
複製程式碼

❌

Widget build(BuildContext context) {
  return new Row(
    children: [
      new RaisedButton(
        child: new Text('Increment'),
      ),
      new Text('Click!'),
    ],
  );
}
複製程式碼

DON’T: 不要使用多餘的 const 修飾物件

✅

const primaryColors = [
  Color("red", [255, 0, 0]),
  Color("green", [0, 255, 0]),
  Color("blue", [0, 0, 255]),
];
複製程式碼

❌

const primaryColors = const [
  const Color("red", const [255, 0, 0]),
  const Color("green", const [0, 255, 0]),
  const Color("blue", const [0, 0, 255]),
];
複製程式碼

異常處理

DO: 使用 rethrow 重新丟擲異常

❌

try {
  somethingRisky();
} catch (e) {
  if (!canHandle(e)) throw e;
  handle(e);
}
複製程式碼

✅

try {
  somethingRisky();
} catch (e) {
  if (!canHandle(e)) rethrow;
  handle(e);
}
複製程式碼

設計規範

AVOID: 避免為了實現流式呼叫而讓方法返回this

✅

var buffer = StringBuffer()
  ..write('one')
  ..write('two')
  ..write('three');
複製程式碼

❌

var buffer = StringBuffer()
    .write('one')
    .write('two')
    .write('three');
複製程式碼

AVOID: 避免使用 FutureOr<T> 作為返回型別

✅

Future<int> triple(FutureOr<int> value) async => (await value) * 3;
複製程式碼

❌

FutureOr<int> triple(FutureOr<int> value) {
  if (value is int) return value * 3;
  return (value as Future<int>).then((v) => v * 3);
}
複製程式碼

AVOID: 避免將bool值直接作為輸入引數

❌

new Task(true);
new Task(false);
new ListBox(false, true, true);
new Button(false);
複製程式碼

✅

Task.oneShot();
Task.repeating();
ListBox(scroll: true, showScrollbars: true);
Button(ButtonState.enabled);
複製程式碼

DON’T: 不要在自定義的 == operator 方法中進行判空

✅

class Person {
  final String name;
  // ···
  bool operator ==(other) => other is Person && name == other.name;

  int get hashCode => name.hashCode;
}
複製程式碼

❌

class Person {
  final String name;
  // ···
  bool operator ==(other) => other != null && ...
}
複製程式碼

附錄

最後。

學習Flutter，你還需要了解這個精美的app?

Todo-List

關於 Google 釋出的 JS 程式碼規範，你需要了解什麼？
2018-04-09
GoJS
Google 的 Java 編碼規範，參考學習！
2019-07-11
GoJava
學習 webpack 前，你需要了解的那些概念
2019-03-03
Web
編碼規範 - 養成良好的Java編碼習慣
2018-06-23
Java
Flutter:Dart 學習筆記
2020-03-18
FlutterDart筆記
Flutter Dart語法學習
2020-07-22
FlutterDart
Flutter學習記錄（一）Dart學習
2019-11-28
FlutterDart
編碼規範系列：css規範
2017-09-29
CSS
《從零開始學Swift》學習筆記（Day 56）—— Swift編碼規範之命名規範
2016-04-05
Swift筆記
Flutter 學習(三) dart基礎
2019-10-30
FlutterDart
我的編碼習慣 —— Controller規範
2018-10-15
Controller
程式碼規範之前端編寫碼規範
2020-10-20
前端
CSS編碼規範
2020-02-14
CSS
Javascript編碼規範
2020-02-14
JavaScript
html編碼規範
2020-02-14
HTML
Swift 編碼規範
2018-02-09
Swift
PHP編碼規範
2017-11-25
PHP
SQL 編碼規範
2016-03-16
SQL
iOS的編碼規範（1.1）
2017-03-01
iOS
Google的Java編碼規範
2014-02-13
GoJava
Flutter學習之Dart語法(二)
2020-03-07
FlutterDart
Flutter學習之Dart語法(一)
2020-02-29
FlutterDart
Flutter學習之Dart語法(三)
2020-03-29
FlutterDart
Flutter學習之Dart語法特性
2019-03-13
FlutterDart
Flutter學習指南：熟悉Dart語言
2018-10-22
FlutterDart
使用git_hooks庫助力Flutter團隊編碼規範
2021-03-15
GitHookFlutter
關於深度學習編譯器，這些知識你需要了解一下
2021-07-06
深度學習編譯
0基礎學習大資料你需要了解的學習路線和方向
2019-01-27
大資料
WEB前端編碼規範
2019-02-15
Web前端
python編碼規範
2021-09-09
Python
前端安全編碼規範
2020-11-03
前端
前端html編碼規範
2018-02-07
前端HTML
Go 編碼規範指南
2016-10-09
Go
Go編碼規範指南
2016-10-09
Go
android 編碼規範
2016-12-01
Android
HTML，CSS編碼規範
2016-11-27
HTMLCSS
阿里Java編碼規範
2017-02-10
阿里Java
[轉]PHP編碼規範
2014-11-30
PHP