code-comment

Files (1)

• SKILL.md

SKILL.md (first lines)

# Code Comment

コメントは、コードから分からないことを読む人に伝えるために書く。

## 原則

- コードから分からないことだけを書く
  - コードを初めて見る人がコードだけを見てそのコメントを書けるなら、そのコメントは不要
- 読み手は言語とフレームワークを知っている前提で書く
  - 構文やAPIの一般的な意味は解説しない。書くのはこのコードベース固有の知識とドメイン知識
- コメントで補う前にコードを直す
  - 名前、関数の分割、型で表現できることはコードで表現する。悪い名前をコメントで説明しない
  - コメントが長くなる、または書きにくいときは、書く前に分割や命名の変更を試す
- コードと同じ抽象度のコメントは繰り返しになる
  - コードより低い抽象度で精度を足すか(単位、境界値、nullの意味、副作用)、高い抽象度で何を達成しようとしているかを足す
- 作業の経緯はコメントではなくコミットメッセージやIssueに書く
- コメントはコードと一緒に更新する
  - 間違ったコメントはコメントなしより悪い
- コメントの言語と形式は周囲のコードとプロジェクトのスタイルガイドに従う。無ければ言語公式の規約に従う

## 書くもの

- なぜそうしているか、なぜ別の方法でないか
  - 一見不要に見える処理や制約は、後から不要と判断されて削除されないよう理由を残す
- このコードが約束する契約と、変更する人が守る制約
  - 周囲の事情は、誰が呼ぶかではなく、このコードが何を守るかとして書く
- 利用者が実装を読まずに使う前提の型や関数には、シグネチャから分からない契約をドキュメンテーションコメントとして書く
  - 契約とは、振る舞い、引数の制約、戻り値、副作用、例外。実装の詳細は書かない
  - 可視性がpublicであることだけを理由に書かない。名前と型で契約が尽きているものに義務的に書かない
- TODO
  - 何が不足していて、何があれば解消できるかを書く

## 書かないもの

- コードの言い換え
- 手順の実況
  - 動作をなぞるコメント、番号付きステップ
- 作業経緯とメタ的な自己解説
  - 指示の出所、会話への参照、修正の経緯、「〜に対応」
  - 変更前との比較や成果の自己申告。「〜から〜に変更」「〜を使うように更新」「安全になった」。差分はdiffで分かる
  - 読み手への注釈。「実際のアプリでは〜」「ここでは簡略化」「必要に応じて〜」
- 周囲からの使われ方
  - 呼び出し元の名前、前後で走る処理。呼び出し元が変わればコメントは腐る
- コメントアウトされたコード
  - 履歴はgitにある

From rmakiyama/skills, MIT.

More from rmakiyama/skills