はじめに
RUNTEQ Advent Calendar 2025の1日目を担当するくうたと申します。
今年のテーマ『みんなにおすすめしたい〇〇tips』です。
みなさんはソースコードにコメントを書いていますか？
動作に一切影響はないですが、私はいろいろ書いてあったほうがありがたいです。
ただし、なんでもありというわけでもないので、読みやすいコードのためのコメントについてまとめてみました。
コメントとはこうあるべきというのは人それぞれあると思いますので、
ここからは私の好き嫌いの話とでも思って頂くのが良いかと思います。
理由を示す！処理を説明するコメント
実装の理由を示すことで安心してコードを扱うことができます。
実装例です。
class SalesReportService
def daily_sales(date)
# 売上の集計は「注文日」ではなく「発送日」を基準にする
# 理由：経理上の売上計上タイミングが「出荷基準」のため
Order.where(shipped_at: date.all_day).sum(:total)
end
end
上記は、指定日の売上集計を行う処理ですが、
コメントには、「指定日の売上集計を行う」というようなことは書いていません。
決して書いてはいけないわけではないですが、それよりも重要なことを書いています。
集計の基準となる日が「注文日」ではなく、「発送日」であるという点です。
また、その理由が経理の都合という点です。
コードは何らかの意図をもって実装されますが、それが必ずしもコードだけで伝わるとは思いません。
今回の場合コードを読めば「発送日」を使用していることは分かります。
しかし、実装者が「注文日」と「発送日」を検討した上で決定したのか、またそれがどのような理由で決定したのかはコードから読み取ることは困難です。
どうしてその実装がされているのか、「理由」、「背景」、「前提」等がコメントで示されていると、安心してコードを扱うことができます。
読みやすくなる！オブジェクトを説明するコメント
変数やメソッドなどのオブジェクトを説明するコメントがあることで、利用する側で実装を確認する必要が減ります。
実装例です。
class OrderService
def confirm_order(order)
reduce_stock(order)
end
# 在庫の減算処理
#
# @param order [Order] 注文オブジェクト
def reduce_stock(order)
order.items.each do |item|
item.product.decrement!(:stock, item.quantity)
end
end
end
上記ではreduce_stockメソッドにコメントを記載しています。
@paramや@returnなどのタグを使ったコメントはYARD形式と呼ばれます。
VSCodeなどのエディタでSolargraphを使っている場合、ホバー時に整形された状態で表示されます。
コード確認時、別ファイルに実装してあるメソッドの定義を参照せずとも、どのようなメソッドで必要な引数が何かを確認することができます。
ホバー時の例
過ぎたるは及ばざるが如し！細かすぎるコメント
行き過ぎたコメントは逆に可読性を下げることになります。
実装例です。
def new
# ユーザーのインスタンスを作成
@user = User.new
end
本来は「@user = User.new」だけ読めば簡単に理解できる処理ですが、
コメントを読むことに時間が割かれてしまいます。
誰がためのコメントか
誰のため、何のためのコメントかということを意識するだけで、
コメントの質は変わってくると思っています。
- 自分の理解のため
英語ネイティブな方なら問題はないと思いますが、
基本はどんなにいい命名をしたとしても日本語のほうが分かりやすくないですか？
複雑な処理にはそれなりのコメントがいると思っています。
実装時は分かっていても、数か月後、または数年後の自分が困らないためのコメントは書くべきです。 - 開発チームのメンバー
個人開発ではない場合、自分以外のメンバーにも実装を分かってもらう必要があります。
プロジェクトの理解が浅い人、製品のドメイン知識が少ない人、技術力が低い人もそのコードを触る可能性はないですか？
自分以外の誰かが読むということを意識したコメントは良いコメントになると思います。
まとめ
私の考える良いコメントをまとめるとこちらです。
- コードの「理由」、「背景」、「前提」等の重要な情報が示されている。
- IDEの機能が利用できる形式で書かれておりオブジェクトを効率的に把握できる。
- 今の自分のためではなく、未来の自分、チームのメンバーのために書かれている。
余談
トピックにするほどの話ではないので、余談です。
- コメントの表記揺れは意識したほうが良い。
ユーザーを示すコメントで、「ユーザー」、「顧客」、「会員」等の表記揺れがあっても、コメントはIDEでチェックされません。 - 文章として読めるものを書く。
当たり前だけど大事です。
主語の無い文章や単語のみの表現では正しい意図が伝わらないかもしれません。 - 本末転倒は良くない。
私の職場では、機能修正時に「日付 担当者 対応の主題」コメントで修正内容をサンドイッチする慣習がありました。
また修正の元となったコードをコメントアウトで残していました。
極端な例でいうと、1行の修正でも、元のたコードのコメントアウト1行、修正後の1行、サンドイッチコメントの2行で4行のコードが出来上がります。
こんなコードが読みやすいわけもなく、コードを読みやすくするためのコメントが思考の邪魔をするという本末転倒の状態でした。これは愚痴です。
今は本当に必要と思った時しか実施していません。
さいごに
ここまでご覧頂きありがとうございました！
いろいろな考え方がありますので、そのうちのひとつと思ってください。
良い実装、良いコメントを生み出していきましょー！！！
RUNTEQ Advent Calendar 2025の1日目を担当させて頂いたくうたでした。
クリスマス楽しみですね。
私はクリスマスマーケットに行ってグリューワインを飲むのが毎年の楽しみです。
いつもは地元の小さめなクリスマスマーケットですが、たまには都内の大きいのに行こうかなー🎄
みなさんも素敵なクリスマスシーズンをお過ごしください🎅
明日以降も素敵な記事が続きますので、ぜひお楽しみに。