誰のためのコメント？ / comments-for-whom

【ペチオブ】2025年 新年会 書き初め LT
というイベントで発表したスライドです。

https://phper-oop.connpass.com/event/339339/

Transcript

1. 誰のためのコメント？ 【ペチオブ】2025年 新年会 書き初めLT 2025.01.09 / Yukimasa Ikeda
2. 目次 1. コメントがないコード 2. 過剰なコメント 3. 意図が伝わらないコメント 4. 理想のコメント 2
3. 1. コメントがないコード function a() { execute(); } 「何をする関数か全く分からない…」 このコードを書いた本人に3年後に聞いても「たぶん緊急対応だった」と返される かも。 コメントがないコードの問題 チームで開発している場合、他のメンバーがコードの意図を理解できない。 自分自身でも時間が経つと記憶が曖昧になる。 3
4. 2. 過剰なコメント 実況中継のようなコメントは、逆にノイズになります。 // ループ処理を開始します for (let i = 0; i < items.length; i++) { process(items[i]); } 「見れば分かる！」と思わずツッコミたくなる。 コメントを書くこと自体が目的になっているケース。 過剰なコメントの問題 コードが変わってもコメントが更新されず矛盾が生じる。 コメントが増えるほど、意図を探すのが困難になる。 4
5. 3. 意図が伝わらないコメント よくある例: 「TODO: 後で直す」 // TODO: 後で直す const result = doSomething(); なぜ後で直す必要があるのか？ どんな状況を想定しているのか？ 意図が伝わらないコメントの問題 他人や未来の自分が見ても、何をしたかったのか分からない。 修正のタイミングや優先度が曖昧になる。 5
6. 4. 理想のコメント コメントを書く際は、以下のポイントを押さえるべきです。 1. 目的を説明する: 「この処理が必要な理由は何か？」を明確にする。 2. 意図を明確にする: 「この方法を選んだ背景は何か？」を伝える。 3. 背景を書く: 設計のトレードオフや、特定の仕様に対応した経緯などを補足する。 理想のコメントの例 // ユーザー一覧を取得する際にページネーションを行うため // クエリにlimitとoffsetを追加しています const users = fetchUsers({ limit: 10, offset: 20 }); 6
7. まとめ コメントは未来の自分や他人に向けて書く。 ただし、コード自体が意図を伝えられるなら、不要なコメントは書かない。 コメントの量より、質が重要。 7
8. 書き初め 8