Comment for Code

Dartの場合、 // は通常のコメントで、 /// がドキュメントコメントになる。

Goではドキュメントコメントの区別はなく、共通して // を使う。

以下、例では // を使用する。

文末に句読点をつける。

マークダウンでは、1つの改行では実際にプレビューしたときに実際に改行されない。

句読点なしで改行を1つしただけでは、行が連結されるため、ドキュメントコメントでは文末に句読点をつける。

Bad
// execute は、実行する関数である
// 引数の args は必要な場合のみ使用する
プレビュー例：execute は、実行する関数である引数の args は必要な場合のみ使用する

Good
// execute は、実行する関数である。
// 引数の args は必要な場合のみ使用する。
プレビュー例：execute は、実行する関数である。引数の args は必要な場合のみ使用する。

改行やリストを意識して使う

WebやIDEでドキュメントコメントを表示した場合に、理解しやすいレイアウトになるように心がける。

• 文脈が異なるテキストであれば、空行を挿入する。
• リストアップできる項目であればリストを使う（空行は不要）

// execute は、実行する関数である。
//
// 以下の引数はv2で追加されたもので、全て任意項目である。
// - keys: 公開されている鍵文字列
// - values: 鍵文字列に対する、公開されていない「値」

TODO コメント

TODO コメントは、後で対応が必要な箇所を示すために使う。

// TODO(username): プレミアム機能フラグを削除する。
// https://github.com/altive/xxx/issues/123

• TODO：後で対応が必要な箇所を示す。
• (username)：コメントを書いた人の GitHub ユーザー名を入れる。
  • 書いた人が対応するわけではない。
  • 記載した人は背景を知っているため、後で対応する人にとって有益な情報となる。
• Issue URL：必ず Issue を作成し、 TODO コメントの下に記載する。
  • 対応が漏れること防ぐ。
  • Issue 番号から該当コードを探しやすくなる。