Flutter 自体の Style Guide から学ぶ #Flutter

/// {@tool sample}
/// An infinite list of children:
///
/// ```dart
/// ListView.builder(
///   padding: EdgeInsets.all(8.0),
///   itemExtent: 20.0,
///   itemBuilder: (BuildContext context, int index) {
///     return Text('entry $index');
///   },
/// )
/// ```
/// {@end-tool}
class ListView { // ...

Use `///` for public-quality private documentation

public な API のコメントは必ず /// だよねという話。
品質が十分でない private な API にだけ // を使おう。

Dartdoc-specific requirements

Dartdoc に従ってドキュメント書こうという話。

/// Creates a foobar, which allows a baz to quux the bar.
///
/// The [bar] argument must not be null.
///
/// The `baz` argument must be greater than zero.
Foo({ this.bar, int baz }) : assert(bar != null), assert(baz > 0);

Use asserts liberally to enforce contracts and invariants

assert() はデバッグモードでだけ有効なんだから、必要と感じたらどんどん入れていこうという話。

Prefer specialized functions, methods and constructors

読み手に意味を直接的に伝えられるメソッドを使おうという話。²

// BAD:
const EdgeInsets.TRBL(0.0, 8.0, 0.0, 8.0);

// GOOD:
const EdgeInsets.symmetric(horizontal: 8.0);

Have good hygiene when using temporary directories

一時ディレクトリはちゃんと管理しようという話。

flutter_ で始まり、ピリオドで終わる一意の名前を付けよう(その後に自動生成されたランダムな文字列を続ける)。

あと、不要になったディレクトリはちゃんと綺麗に片付けること!
テストでは tryToDelete を使おう。³

Perform dirty checks in setters

セッターで Dirty チェックをしようという話。

Dirty チェックというのは、変更された値がアプリの他の箇所と同期されているかをチェックすること。
例えば、セットのタイミングで Dirty であることをマーキングしておくにはこんな感じで書く。

TheType get theProperty => _theProperty;
TheType _theProperty;
void set theProperty(TheType value) {
  assert(value != null);
  if (_theProperty == value)
    return;
  _theProperty = value;
  markNeedsWhatever(); // the method to mark the object dirty
}

Common boilerplates for `operator ==` and `hashCode`

operator == と hashCode をオーバーライドする時はこう書こうという話。

@override
bool operator ==(Object other) {
  if (other.runtimeType != runtimeType)
    return false;
  final Foo typedOther = other;
  return typedOther.bar == bar
      && typedOther.baz == baz
      && typedOther.quux == quux;
}

@override
int get hashCode => hashValues(bar, baz, quux);

オブジェクトがたくさんプロパティを持つなら、operator == を頭に置くことも検討しよう。

Override toString

toString をオーバーライドしてデバッグに使うよりも、Diagnosticable を使おうという話。
devtools や IDEでの調査も捗る。

Prefer naming the argument to a setter `value`

特に理由がない限りセッターの引数は value にしようという話。

おわりに

driver test まわりの挙動に色々疑問があってソース追いかけていたのに、いつの間にか Style Guilde 読んでた...

中には analysis_options.yaml に書いておけばいいだけのものもあるので設定大事。 ↩
それっぽいメソッドが生えてないかドキュメントを逐次確認するのが大切ってことですね。 ↩
例えばこんな感じにね! flutter_tools/test/integration/flutter_run_test.dart#L29 ↩