はじめに
現在スクール課題でRailsでSNS風アプリケーションを開発しています。
開発を始めた当初、自分は「コメントは多ければ多いほど親切」くらいに考えていました。しかし、他の人が書いたコードを読んだり、有名な技術書を読んだりする中で、コメントにはコードの価値を大きく高める「良いコメント」と、むしろ価値を下げてしまう「悪いコメント」があることに気づきました。
今回は、自省と学びを元に、保守性・可読性を高めるコメントの書き方について、その原則をまとめてみました。
コメントの基本方針：「What」より「Why」
優れたコメントの原則は、コードを読めばわかるWhat（何をしているか）ではなく、コードだけではわからないWhy（なぜそうしているか）を説明することです。
コードは user.name = "Taro" のように、「何をしているか」を語ります。しかし、「なぜTaroという名前を代入する必要があるのか」というビジネス上の背景や技術的な意図までは語れません。その「なぜ」を補うのが、良いコメントの役割です。
✅ コードの価値を高める「良いコメント」
1. 意図や背景を説明するコメント
コードだけでは読み取れない「ビジネス上の理由」や「技術的な判断」を書き残します。これにより、他の開発者や未来の自分が仕様を理解しやすくなります。
# GitHub経由の新規ユーザーは、電話番号などの追加情報が未入力の状態。
# そのため、バリデーションを通過させるために強制的に情報入力ページへリダイレクトさせる。
if user.new_record?
# ...
end
2. 複雑なロジックを要約するコメント
正規表現や難解なアルゴリズムなど、一読で理解しにくいコードの前に、それが何をするものなのかを平易な言葉で要約します。
# 全角カタカナ、半角カタカナ、長音符（ー）のみを許可する正規表現
VALID_KATAKANA_REGEX = /\A[\p{katakana}\u{ff65}-\u{ff9f}ー]+\z/
3. TODO や FIXME といった決まった形式のコメント
「今はやらないが、将来的には対応が必要なこと」や「既知の問題点」に決まったキーワードで目印をつけます。
-
TODO: 今後追加する機能やリファクタリングのメモ -
FIXME: 既知の問題があり、修正が必要な箇所
# TODO: N+1問題が発生しているため、includesを使用して最適化する
@posts = Post.all.order(created_at: :desc)
# FIXME: この外部APIは稀にタイムアウトするため、リトライ処理を実装する必要がある
response = ThirdPartyApi.fetch_data
❌ コードの価値を下げる「悪いコメント」
1. コードの「日本語訳」にすぎないコメント
コードを読めばわかることをそのまま書いたコメントは、コードの重複であり、ノイズでしかありません。
# ❌ 言わなくてもわかる
# iを1増やす
i += 1
2. メンテナンスされていない古いコメント
コードを修正した際にコメントを直し忘れると、コードとコメントが食い違い、混乱を招きます。間違ったコメントは、コメントがないよりも害悪です。
3. コメントアウトされたコードの残骸
Gitのようなバージョン管理システムを使っているなら、不要になったコードはコメントアウトせず、潔く削除しましょう。過去のコードはGitの履歴がすべて記憶しています。
まとめ
良いコードは「何をしているか」を明確に語り、良いコメントは「なぜそうしているか」を雄弁に語ります。
この意識を持つだけで、コードの質も、チーム開発の効率も格段に上がるはずです。自分もまだまだ勉強中ですが、この記事が同じように頑張る誰かの助けになれば嬉しいです。