はじめに

仕事がら、ほかの人が作成したプログラムを見ることが多いのですが、最近まったくソースコードにコメントがないものを見る機会がありました。
そのことを同僚に話してみたところ、「ソースコードにコメントは書くべきでない」という考え方があるのを知りました。

私自身は自分の書いたプログラムのソースコードレビューをしてもらったときに、「コメントをちゃんと書こうね」といわれたりしていました。また、見知らぬソースコードを解読するときに「少しはコメント書いてくれないと何やっているかわからないよー」と思ったりしたこともありました。なので、自分の中では「コメントはきちんと書くもの」という考えしか持っていませんでした。

そんな中で、同僚から聞いた「ソースコードにコメントは書くべきでない」という考え方にちょっとびっくりしてしまいました。ただ、インターネットなどで検索すると、「ソースコードにコメントは必要」派の考え方と、「ソースコードにコメントは不要」派の考え方の人がどちらも結構いるようで、「ふーむ、そうなんだねえ」と考えさせられました。

そこで、それぞれの考え方について調べてまとめてみようと思い、この記事を書きました。

まずはCopilotさんに聞いてみよう

ということで、最近は調べごとの第一歩は生成AIを使うことが多いので、Copilotさんに「プログラミングをする際にソースコードにコメントをつけるのは不要という人と必須という人がいます。それぞれどういう主張なのかをまとめてください。」と聞いてみました。

その結果がこちら。

ソースコードへのコメントの必要性については、開発者の考え方やチームの方針によって意見が分かれます。主な主張をまとめると以下のようになります。

コメント不要派の主張

コード自体が十分に明瞭：適切な変数名、関数名、クラス設計をすれば、コードの意図が自然に伝わるため、コメントは不要。

メンテナンスの手間が増える：コードが変更されたときにコメントを更新し忘れると、誤った情報を伝える可能性がある。

冗長な説明が逆に読みにくくする：意味のないコメント（例：「変数 x に値を代入する」）は、コードの可読性を損ねる。

良いドキュメントがあれば十分：設計書やドキュメントでコードの意図を説明すれば、コード内部のコメントは不要になる。

コメント必須派の主張

コードの意図を明示できる：変数や関数名だけでは伝わらない背景や目的を説明できるため、理解が容易になる。

複雑な処理を解説できる：アルゴリズムや最適化の意図など、コードからすぐに読み取れない情報を補足できる。

他の開発者や将来の自分への助けとなる：過去に書かれたコードを見直した際に、コメントがあるとスムーズに理解できる。

デバッグや保守の助けになる：特定の処理がバグ回避のために存在している場合、その理由をコメントで説明することで誤った削除を防げる。

どちらの立場にも合理的な理由がありますが、一般的には「コードの可読性を損なわない適切なコメント」が推奨されます。たとえば、関数の役割を簡潔に説明したり、難解なロジックに補足を入れるなど、必要最小限のコメントが最適です。実際の開発環境では、チームの方針やプロジェクトの規模に応じて適切なバランスを取ることが重要ですね。

確かにどちらのご意見もなるほどというところ。
もともと私はコメント書いたほうがいいという考えだったので、コメント必須派の主張は全部納得できるのですが、コメント不要派の意見もなるほどなーという感じでした。特に、「メンテナンスの手間が増える」「冗長な説明が逆に読みにくくする」はその通りだなと。
私自身もソースを読んでいて、「いや、このコメントの内容、ソースコード修正前古い内容のままじゃない？」とか

// 変数xに100を代入する
x = 100;

みたいなコメントを見て、「え、このコメントはいらないでしょ。」と思ったことも多数あったので、理解できるなあと思いました。

ただ、「良いドキュメントがあれば十分」という考えは、理解はできるのですが、ちょっと納得いかないところもありました。今だったら、javadocとかdoxygenとか、ソースコードコメントから仕様書を自動生成できるようなツールもあります。なので、ソースコードにきちんとコメント書いておいたら、ドキュメントは生成できるし、メンテナンスも楽なんじゃない？とか思ったり。

Qiitaでさがしてみた

せっかくQiitaというサイトがあるので、Qiitaの中でソースコードのコメントについて書いてある記事を探してみました。

いろいろなご意見がありますが、私は

できる限りわかりやすいコードを書こう（変数名、関数／メソッド名、ロジックなど）
意味のあるコメントを書こう（ソースコードだけではわからない意図など）
うそのコメントは書かないで！（ソースだけ直して、コメントなおさないとこれがおこる）
とおっしゃっている方が多いのかなあという印象でした。

おわりに

いろいろとご意見はありますが、私は「コメントがないコードはだめだ！」とか「コメントを書くのは意味ない！」などと、極論で議論しないほうがいいのかなと思います。

理想論は、コメントがなくてもソースコードだけですべてが理解できることなのでしょう。
ただ、そのようなソースコードを書くのはかなりのスキルが必要なのかなと思います。そこを目指すのは重要と思いますが、わかりづらいソースを書いて「コメントを書くのは意味がない！」といって、コメントを書かないのは、それはそれでどうなんだろうと思います。

プログラミングを仕事にしている場合、ほかの人が自分のソースコードを読んで理解してもらうことは、避けられないことだと思っています。コードレビューしかり、担当者間の引継ぎ、保守しかり。

その際に、ソースコード読んでもさっぱりわからないということにならないように、わかりやすいソースコードを書くことと、意味のあるコメントを書くことの2つを気を付けながらプログラミングをするひつようがあるのだろうなーと感じました。