- なぜ「why not」コメントなのか？ 「not comments」がなぜないのか、ではない
- 「なぜ『なぜうまくいかなかったのか』についてのコメントを残さないのですか？ 『なぜコメントを書かなかったのか』という理由を聞いているのではありません。」
Why Not Comments
- コードは構造化された機械言語で書かれ、コメントは表現力の豊かな人間の言語で書かれる
- 「何を」コメントするのではなく、できるだけ多くの情報を識別子に含めるべきだという意味
- 最近では「なぜ」もコメントに含めず、
LongFunctionNames やテストケース名に含めるべきだという主張もある
- 「自己文書化」されたコードベースは、識別子を通じてドキュメントを追加する
最近の例
Logic for Programmers に出てきた例- epub ビルドが数式記号(
\forall)を記号(∀)に変換できない問題が発生
- 数式文字列のトークンを手動で Unicode に置き換えるスクリプトを書いた
- 16個の数式記号をそれぞれ置き換える方式で書いたが、これは非効率
- シンプルにコメントを書いて解決
- 「各文字列に対して16回繰り返すが、今の本には数式文字列が25個しかなく、その大半は5文字未満なので、それでも十分に速い」
なぜコメントを書くべきか
- 遅いコードが問題を起こしていなくてもコメントを書くべき理由
- 将来そのコードが問題になる可能性がある
- コメントは、トレードオフを認識していることを示す
- 後でプロジェクトを見直したとき、なぜ遅いコードを書いたのか理解できる
なぜ自己文書化は不可能なのか
RunFewerTimesSlowerAndSimplerAlgorithmAfterConsideringTradeOffs のような長い関数名は、トレードオフを説明しない- 関数や変数の識別子には1つの情報しか含められない
- コメントをテストで置き換えることもできない
- 自己文書化はコードが何をするかを説明するが、否定的な情報はコードが何をしないかを説明する
ニュースレター末尾の推測
- 「なぜダメなのか」コメントを反事実的なケースとして考えられるのか気になっている
- 人間のコミュニケーションの抽象化は自己文書化できないのか？
- 比喩、不確実性、倫理的主張などを自己文書化できるのか？
GN⁺の要約
- この記事はコードコメントの重要性とその限界を扱う
- コメントによってコードのトレードオフを明確にし、将来の保守を容易にする
- 自己文書化の限界とコメントの必要性を強調する
1件のコメント
Hacker Newsの意見
コードにコメントを書くときは、主に「なぜ」と「なぜうまくいかないのか」を説明する。コードが複雑な場合は、「何をしているか」を簡潔に説明するのも有用
ジュニアエンジニアはコードが何をするかを説明するコメントを書き、中堅エンジニアはなぜそのように書いたのかを説明し、シニアエンジニアはなぜ別の方法で書かなかったのかを説明する
メンテナ向けのコメントテンプレートを使う
コード内の意外な部分にコメントを付けることが重要
コメントの重要性を強調しており、特に自分のコードを5年後、10年後、15年後にも保守しなければならない場合に役立つ
「素朴な解決策ではないもの」にコメントを付けるのがよい
長い関数名やテストケース名にコメントを含めるのがよい
デバッグログによって、入力が元の設計上の制約より大きい場合に警告を追加するのも有用
コメントやドキュメントコメントを多用することを好む
コードレビューで予想される批判をあらかじめ防ぐために、「Xをしなかった理由はYだから」というコメントを書く