注釋

要像句子一樣格式化

除非是區(qū)分大小寫(xiě)的標(biāo)識(shí)符，否則第一個(gè)單詞要大寫(xiě)覆积。以句號(hào)結(jié)尾(或“!”或“?”)搂誉。對(duì)于所有的注釋都是如此：doc注釋徐紧、內(nèi)聯(lián)內(nèi)容，甚至TODOs炭懊。即使是一個(gè)句子片段并级。

  greet(name) {
    // Assume we have a valid name.
    print('Hi, $name!');
  }

不推薦如下寫(xiě)法：

  greet(name) {
    /* Assume we have a valid name. */
    print('Hi, $name!');
  }

可以使用塊注釋(/…/)臨時(shí)注釋掉一段代碼，但是所有其他注釋都應(yīng)該使用//

Doc注釋

使用///文檔注釋來(lái)記錄成員和類(lèi)型侮腹。

使用doc注釋而不是常規(guī)注釋?zhuān)梢宰宒artdoc找到并生成文檔嘲碧。

  /// The number of characters in this chunk when unsplit.
  int get length => ...

由于歷史原因，達(dá)特茅斯學(xué)院支持道格評(píng)論的兩種語(yǔ)法:///(“C#風(fēng)格”)和/*… /(“JavaDoc風(fēng)格”)父阻。

我們更喜歡/// 因?yàn)樗o湊愈涩。/*和/在多行文檔注釋中添加兩個(gè)無(wú)內(nèi)容的行望抽。

在某些情況下，///語(yǔ)法也更容易閱讀履婉，例如文檔注釋包含使用*標(biāo)記列表項(xiàng)的項(xiàng)目符號(hào)列表糠聪。

考慮為私有api編寫(xiě)文檔注釋

Doc注釋并不僅僅針對(duì)庫(kù)的公共API的外部使用者。它們還有助于理解從庫(kù)的其他部分調(diào)用的私有成員

用一句話(huà)總結(jié)開(kāi)始doc注釋

以簡(jiǎn)短的谐鼎、以用戶(hù)為中心的描述開(kāi)始你的文檔注釋?zhuān)跃涮?hào)結(jié)尾。

/// Deletes the file at [path] from the file system.
void delete(String path) {
  ...
}

不推薦如下寫(xiě)法：

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

“doc注釋”的第一句話(huà)分隔成自己的段落

在第一個(gè)句子之后添加一個(gè)空行趣惠，把它分成自己的段落

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

標(biāo)識(shí)符三種類(lèi)型

大駝峰

類(lèi)狸棍、枚舉、typedef和類(lèi)型參數(shù)

  class SliderMenu { ... }
  
  class HttpRequest { ... }
  
  typedef Predicate = bool Function<T>(T value);

使用小寫(xiě)加下劃線(xiàn)來(lái)命名庫(kù)和源文件

  library peg_parser.source_scanner;
  
  import 'file_system.dart';
  import 'slider_menu.dart';

不推薦如下寫(xiě)法：

  library pegparser.SourceScanner;
  
  import 'file-system.dart';
  import 'SliderMenu.dart';

使用小寫(xiě)加下劃線(xiàn)來(lái)命名導(dǎo)入前綴

  import 'dart:math' as math;
  import 'package:angular_components/angular_components'
      as angular_components;
  import 'package:js/js.dart' as js;

不推薦如下寫(xiě)法：

  import 'dart:math' as Math;
  import 'package:angular_components/angular_components'
      as angularComponents;
  import 'package:js/js.dart' as JS;

使用小駝峰法命名其他標(biāo)識(shí)符

  var item;
  
  HttpRequest httpRequest;
  
  void align(bool clearItems) {
    // ...
  }

優(yōu)先使用小駝峰法作為常量命名

  const pi = 3.14;
  const defaultTimeout = 1000;
  final urlScheme = RegExp('^([a-z]+):');
  
  class Dice {
    static final numberGenerator = Random();
  }

不推薦如下寫(xiě)法：

  const PI = 3.14;
  const DefaultTimeout = 1000;
  final URL_SCHEME = RegExp('^([a-z]+):');
  
  class Dice {
    static final NUMBER_GENERATOR = Random();
  }

不使用前綴字母

因?yàn)镈art可以告訴您聲明的類(lèi)型味悄、范圍草戈、可變性和其他屬性，所以沒(méi)有理由將這些屬性編碼為標(biāo)識(shí)符名稱(chēng)侍瑟。

  defaultTimeout #GOOD
  kDefaultTimeout #BAD

文件名使用 _下劃線(xiàn)命名規(guī)則

good_man.dart #GOOD
goodMan.dart #BAD

包名使用 _下劃線(xiàn)命名規(guī)則

import 'package:javascript_utils/javascript_utils.dart' as js_utils; #GOOD
import 'package:javascriptUtils/javascript_utils.dart' as js_utils; #BAD

文件導(dǎo)入與導(dǎo)出

• 文件導(dǎo)入：統(tǒng)一引用使用絕對(duì)路徑唐片。
• 在所有導(dǎo)入之后，在單獨(dú)的部分中指定導(dǎo)出

  import 'package:project/src/error.dart';
  import 'package:project/src/foo_bar.dart';
  
  export 'package:project/src/error.dart';

不推薦如下寫(xiě)法：

  import 'package:project/src/error.dart';
  export 'package:project/src/error.dart';
  import 'package:project/src/foo_bar.dart';

所有流控制結(jié)構(gòu)涨颜，請(qǐng)使用大括號(hào)

這樣做可以避免懸浮的else問(wèn)題

  if (isWeekDay) {
    print('Bike to work!');
  } else {
    print('Go dancing or read a book!');
  }

例外

一個(gè)if語(yǔ)句沒(méi)有else子句费韭，其中整個(gè)if語(yǔ)句和then主體都適合一行。在這種情況下庭瑰，如果你喜歡的話(huà)星持，你可以去掉大括號(hào)

  if (arg == null) return defaultValue;

如果流程體超出了一行需要分劃請(qǐng)使用大括號(hào)：

  if (overflowChars != other.overflowChars) {
    return overflowChars < other.overflowChars;
  }

不推薦如下寫(xiě)法：

  if (overflowChars != other.overflowChars)
    return overflowChars < other.overflowChars;

字符串的使用

使用相鄰字符串連接字符串文字

如果有兩個(gè)字符串字面值(不是值，而是實(shí)際引用的字面值)弹灭，則不需要使用+連接它們督暂。就像在C和c++中，簡(jiǎn)單地把它們放在一起就能做到穷吮。這是創(chuàng)建一個(gè)長(zhǎng)字符串很好的方法但是不適用于單獨(dú)一行逻翁。

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

不推薦如下寫(xiě)法:

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

優(yōu)先使用模板字符串

'Hello, $name! You are ${year - birth} years old.';

在不需要的時(shí)候，避免使用花括號(hào)

  'Hi, $name!'
  "Wear your wildest $decade's outfit."

不推薦如下寫(xiě)法：

  'Hello, ' + name + '! You are ' + (year - birth).toString() + ' y...';

不推薦如下寫(xiě)法：

  'Hi, ${name}!'
  "Wear your wildest ${decade}'s outfit."

集合

盡可能使用集合字面量

如果要?jiǎng)?chuàng)建一個(gè)不可增長(zhǎng)的列表捡鱼，或者其他一些自定義集合類(lèi)型八回，那么無(wú)論如何，都要使用構(gòu)造函數(shù)堰汉。

  var points = [];
  var addresses = {};
  var lines = <Lines>[];

不推薦如下寫(xiě)法：

  var points = List();
  var addresses = Map();

不要使用.length查看集合是否為空

if (lunchBox.isEmpty) return 'so hungry...';
if (words.isNotEmpty) return words.join(' ');

不推薦如下寫(xiě)法：

  if (lunchBox.length == 0) return 'so hungry...';
  if (!words.isEmpty) return words.join(' ');

考慮使用高階方法轉(zhuǎn)換序列

如果有一個(gè)集合辽社，并且希望從中生成一個(gè)新的修改后的集合，那么使用.map()翘鸭、.where()和Iterable上的其他方便的方法通常更短滴铅，也更具有聲明性

  var aquaticNames = animals
      .where((animal) => animal.isAquatic)
      .map((animal) => animal.name);

不要使用List.from()，除非打算更改結(jié)果的類(lèi)型

給定一個(gè)迭代就乓，有兩種明顯的方法可以生成包含相同元素的新列表

var copy1 = iterable.toList();
var copy2 = List.from(iterable);

明顯的區(qū)別是第一個(gè)比較短汉匙。重要的區(qū)別是第一個(gè)保留了原始對(duì)象的類(lèi)型參數(shù)

// Creates a List<int>:
var iterable = [1, 2, 3];

// Prints "List<int>":
print(iterable.toList().runtimeType);

// Creates a List<int>:
var iterable = [1, 2, 3];

// Prints "List<dynamic>":
print(List.from(iterable).runtimeType);

參數(shù)的使用

使用=將命名參數(shù)與其默認(rèn)值分割開(kāi)

由于遺留原因拱烁，Dart均允許“:”和“=”作為指定參數(shù)的默認(rèn)值分隔符。為了與可選的位置參數(shù)保持一致噩翠，使用“=”戏自。

  void insert(Object item, {int at = 0}) { ... }

不推薦如下寫(xiě)法：

  void insert(Object item, {int at: 0}) { ... }

不要使用顯式默認(rèn)值null

如果參數(shù)是可選的，但沒(méi)有給它一個(gè)默認(rèn)值伤锚，則語(yǔ)言隱式地使用null作為默認(rèn)值擅笔，因此不需要編寫(xiě)它

void error([String? message]) {
  stderr.write(message ?? '\n');
}

不推薦如下寫(xiě)法:

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

變量

不要顯式地將變量初始化為空

在Dart中，未顯式初始化的變量或字段自動(dòng)被初始化為null屯援。不要多余賦值null

int _nextId = null;      #BAD
int? _nextId;             #GOOD

常用遍歷聲明規(guī)范

#BAD
var points = List();
var addresses = Map();
var uniqueNames = Set();
var ids = LinkedHashSet();
var coordinates = LinkedHashMap();

#GOOD
var points = [];
var addresses = <String,String>{};
var uniqueNames = <String>{};
var ids = <int>{};
var coordinates = <int,int>{};

避免儲(chǔ)存你能計(jì)算的東西

在設(shè)計(jì)類(lèi)時(shí)猛们，您通常希望將多個(gè)視圖公開(kāi)到相同的底層狀態(tài)。通常你會(huì)看到在構(gòu)造函數(shù)中計(jì)算所有視圖的代碼狞洋，然后存儲(chǔ)它們:

應(yīng)該避免的寫(xiě)法：

  class Circle {
    num radius;
    num area;
    num circumference;
  
    Circle(num radius)
        : radius = radius,
          area = pi * radius * radius,
          circumference = pi * 2.0 * radius;
  }

如上代碼問(wèn)題：

• 浪費(fèi)內(nèi)存
• 緩存的問(wèn)題是無(wú)效——如何知道何時(shí)緩存過(guò)期需要重新計(jì)算弯淘？

推薦的寫(xiě)法如下：

  class Circle {
    num radius;
  
    Circle(this.radius);
  
    num get area => pi * radius * radius;
    num get circumference => pi * 2.0 * radius;
  }

類(lèi)成員

不要把不必要地將字段包裝在getter和setter中

推薦寫(xiě)法:

class Box {
  var contents;
}

不推薦如下寫(xiě)法：

  class Box {
    var _contents;
    get contents => _contents;
    set contents(value) {
      _contents = value;
    }
  }

優(yōu)先使用final字段來(lái)創(chuàng)建只讀屬性

尤其對(duì)于 StatelessWidget

在不需要的時(shí)候不要用this

不推薦如下寫(xiě)法：

  class Box {
    var value;
    
    void clear() {
      this.update(null);
    }
    
    void update(value) {
      this.value = value;
    }
  }

推薦如下寫(xiě)法：

  class Box {
    var value;
  
    void clear() {
      update(null);
    }
  
    void update(value) {
      this.value = value;
    }
  }

構(gòu)造函數(shù)

盡可能使用初始化的形式

不推薦如下寫(xiě)法：

  class Point {
    late num x, y;
    Point(num x, num y) {
      this.x = x;
      this.y = y;
    }
  }

推薦如下寫(xiě)法：

class Point {
  num x, y;
  Point(this.x, this.y);
}

構(gòu)造函數(shù)以;分號(hào)結(jié)尾，替代{}

class Point {
  int? x, y;
  Point(this.x, this.y) {}    #BAD 
  Point(this.x, this.y);      #GOOD
}

聲明方法或函數(shù)時(shí)吉懊，始終要指定返回類(lèi)型庐橙。

void main() { }

_Foo _bar() => _Foo();

class _Foo {
  int _foo() => 42;
}

使用父類(lèi)參數(shù)要用overrides修飾

abstract class Dog {
  String get breed;
  void bark() {}
}

class Husky extends Dog {
  @override
  final String breed = 'Husky';
  @override
  void bark() {}
}

避免使用函數(shù)或方法名稱(chēng)中的名稱(chēng)來(lái)描述一個(gè)形參。

推薦如下：

list.add(element);
map.remove(key);

不建議：

list.addElement(element);
map.removeKey(key);

也有例外借嗽，當(dāng)用以消除有相似名稱(chēng)但不同類(lèi)型參數(shù)的歧義時(shí)：

map.containsKey(key);
map.containsValue(value);

不要使用new

Dart2使new 關(guān)鍵字可選

推薦寫(xiě)法：

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

不推薦如下寫(xiě)法：

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

異步

優(yōu)先使用async/await代替原始的futures

async/await語(yǔ)法提高了可讀性态鳖，允許你在異步代碼中使用所有Dart控制流結(jié)構(gòu)。

  Future<int> countActivePlayers(String teamName) async {
    try {
      var team = await downloadTeam(teamName);
      if (team == null) return 0;
  
      var players = await team.roster;
      return players.where((player) => player.isActive).length;
    } catch (e) {
      log.error(e);
      return 0;
    }
  }

當(dāng)異步?jīng)]有任何用處時(shí)恶导，不要使用它

如果可以在不改變函數(shù)行為的情況下省略異步郁惜，那么就這樣做。甲锡、

  Future afterTwoThings(Future first, Future second) {
    return Future.wait([first, second]);
  }

不推薦寫(xiě)法：

  Future afterTwoThings(Future first, Future second) async {
    return Future.wait([first, second]);
  }

常用編碼規(guī)則

避免在條件表達(dá)式中使用bool值兆蕉。

condition ? true : boolExpression    #BAD
condition ? false : boolExpression   #BAD

condition || boolExpression          #GOOD
!condition && boolExpression         #GOOD

set方法不要帶返回值

void set speed(int ms);  #BAD
set speed(int ms);  #GOOD

聲明void返回值的函數(shù)不要返回null

void f1() {
  return null;      #BAD
  return;           #GOOD
}
Future<void> f2() async {
  return null;   #BAD
  return;        #GOOD
}

判斷Type不要使用ToString()

void bar(Object other) {
  if (other.runtimeType.toString() == 'Bar') {  #BAD   
  if (other is Bar){                            #GOOD

    doThing();
  }
}

異步方法不要直接返回void

void f() async {}          #BAD
Future<void> f() async {}  #GOOD

StreamSubscription一定要記得cancel

使用 ??、??=缤沦、?. 代替判斷null

v = a == null ? b : a; #BAD
v = a ?? b;            #GOOD

#不推薦
String get fullName {
  if (_fullName == null) {
    _fullName = getFullUserName(this);
  }
  return _fullName;
}

# 推薦用法
String get fullName {
  return _fullName ??= getFullUserName(this);
}


v = a == null ? null : a.b;     #BAD
v = a?.b;                       #GOOD

感謝：
FlutterLint開(kāi)啟規(guī)則
編寫(xiě)高質(zhì)量Dart程序-文檔注釋參考