fresh digitable

めんどくさかったなってことを振り返ったり振り返らなかったりするための記録

effective dartを一言ぐらいでまとめていく(Document編)

続きです:akihito104.hatenablog.com

Document

dart.dev

  • そのコードを書いている間はコードの意図が明白であったとしても、そのコードを初めて見る人や、将来の自分でさえも、その時の文脈を知らないかもしれない。
  • コメントを書くのには数秒程度しかかからないが、それによってたくさんの人の時間を節約できる。
  • コメントは自分たちが思っている以上にもっと書いた方がいい。

comment

  • コメントは文章のように書く。大文字で始めて、ピリオドで終わる。
  • コメントにはブロックコメントを使わない。ブロックコメントはコードの一時的なコメントアウトの時だけにする。

doc comments

/// で書き始めるとdartdocにできていい感じの見た目のページを作れる。

  • メンバや型のドキュメントには///を使う。歴史的経緯でJavadoc風の /* ... /も使えるけど、///の方が*を箇条書きのマークとして使えるのでおすすめ。
  • publicなAPIにはドキュメントを書くのが望ましい。
  • ライブラリレベルのdoc commentを検討する。クラスがプログラムの唯一の構成単位であるJavaとは違い、Dartにおけるライブラリは、ユーザーがそれを直接使い、importし、それについて考える実態である。libraryディレクティブは、ライブラリのコンセプトや提供する機能を説明するのによい場所である。ドキュメントはファイルの先頭にあるlibraryディレクティブのすぐ上に書く。libraryディレクティブがない時は追加しよう。次のようなことを書くとよい
    • ライブラリが何をするためのものなのか、1行で表す。
    • ライブラリ全体を通して使う用語を説明する
    • APIをくまなく使うようないくつかのコードサンプル
    • 最も重要な、または共通的なクラスや関数へのリンク
    • このライブラリで取り扱う領域に関する外部への参照
  • private APIにもドキュメントを書くよう考える。
  • ドキュメントは1行の要約から始める。ただの断片的な文だけで十分な場合もあるが、読み手がこの先も読むに値するか判断できるようなものが望ましい。
  • 最初の文章とdoc commentとの間に空行を入れて分ける。
  • 周囲の文脈を冗長に書かない。doc commentを読む人はそのクラスや、そのメンバのシグネチャなら簡単に把握できるので、そういったことをわざわざ特定のメンバのdoc commentに書く必要はない。
  • 関数やメソッドのコメントは三人称の動詞で書き始めるのが望ましい。
  • 変数やgetter, setterのコメントは名詞で書き始めるのが望ましい。何が得られるのかを強調するべき。もしプロパティにgetterとsetterが両方ともある時、dartdocはそれらを1つのプロパティとみなすので片方にだけドキュメントを書けばよい。両方に書いてある場合は、setterの方が無視される。
  • ライブラリや型のコメントは名詞で書き始めるのが望ましい。クラスのドキュメントがしばしば最も重要になる。型の不変性を記載したり、使う用語を確立したり、クラスのメンバに対するコンテキストを提供することにもなる。少しでいいのでクラスのドキュメント作成を頑張ると、ほかのドキュメンテーションをシンプルにできることもある。
  • サンプルコードを付けるのを考慮する。
  • 大かっこをつかってスコープ内識別子を参照する。クラス内のメンバや名前付きコンストラクタを参照するときはドットでつなげればよい。
  • パラメータや戻り値、例外の説明は文章の中で行う。特別なシンタックスを使うなどして個別に詳細に書く言語もあるが、Dartはではパラメータなどを大かっこで括って本文内に統合する。
  • doc commentはメタデータアノテーションの上に書く。

markdown

  • 過度に使いすぎるのを避ける。
  • フォーマットにHTMLを使うのを避ける。
  • コードブロックにはバックティックフェンス (```) を使うのが望ましい。

writing

  • 簡潔に書く。
  • 略語や頭字語は使わない。
  • メンバのインスタンスに対して言及するときは、theではなくthisを使うのが好ましい。