GemfileのコメントはWHATではなくWHYを記載しよう

はじめに

Gemfile内のコメントを見直す機会があったため、効果的なコメントの記述方法について再確認しました。

この記事では、コメントに記載すべき「WHAT」と「WHY」の違いや、よくあるミス、具体的な記述例をまとめます。

WHATとWHYの違い

• WHAT（何をしているか？）：コードが何をするか、どのように動作するかを説明
• WHY（なぜそれをするのか？）：そのコードが必要な理由、背景、意図を説明

多くの場合、コード自体やGemの公式ドキュメントを読めば「WHAT」は理解できます。

しかし「WHY」はコードだけでは伝わらないことが多く、保守運用を行う際の障壁となります。

Gemfileのコメントでありがちなミス

Gemfile

# 認証機能を提供するGem
gem 'devise'

# ページネーションを実装
gem 'kaminari'

たとえば上記のようなコメントは一見親切に思えますが、実際には冗長です。

Gemの名前からすぐに推測もしくは検索できる情報だからです。

これではコメントの価値が半減してしまいます。

WHYを記載するメリット

1. 将来の変更に備える；特定のGemのバージョンを固定している理由や削除できない訳を記載することで、後続の開発者がメンテナンスする際のリスクを減らせます
2. 問題の再発防止；過去に遭遇したバグや互換性の問題を記載しておくと、同じ理由で悩む時間を節約できます
3. ナレッジ共有：「なぜその選択をしたのか」を記すことでチーム全体の理解が深まります

具体例

バージョンを上げられない場合

Gemfile

# Rails 7へのアップグレードで互換性の問題が発生するため、バージョンを固定
gem 'some_gem', '~>1.2.3'

Gemを削除してはいけない場合

Gemfile

# 旧システムとの連携で必要なので削除不可
gem 'legacy_support_gem'

特定のGemを採用した理由

Gemfile

# パフォーマンスの問題からcarrierwaveではなくactive_storageを使用
gem 'active_storage'

まとめ

Gemfileのコメントでは「WHAT」ではなく「WHY」に焦点を当てることで、可読性と保守性を向上させられます。

無意味なコメントを避け、必要な情報を的確に記述する習慣をつけていきましょう。