なぜ、ソースコメントを残すよりソースコードを短くする方が10倍良いのか？

はじめに

かつてのソフトウェア開発では、「コメントを多く書くこと」 が美徳とされていました。特に1990〜2000年代の現場では、コードの上部に長い説明文を並べ、「なぜそう書いたか」「何をしているか」を文章で補うことが一般的でした。しかし、現代の開発環境ではIDEや静的解析ツール、さらにはAIまでもがコードを自動的に理解し、構造や意図を説明できるようになりました。このような時代において、コメントの多さはむしろ害になることが増えています。

本稿では、なぜ「ソースコメントを残すよりもソースを短くする方が10倍良いのか」について、認知心理学的観点、ソフトウェア工学的観点、そしてAI時代の実践的観点から考察します。

コメントは思考の補助であり、思考の代替ではない

コメントを書くこと自体は悪いことではありません。本来、コメントは「コードに直接書けない事情」や「一時的な回避策（ワークアラウンド）」を説明するために存在します。しかし、しばしばそれが**“思考の代替”**になってしまうことがあります。

「後で分かるようにコメントを残しておこう」という発想は、一見誠実に見えて、実は構造的欠陥を覆い隠す行為です。コメントを書かないと理解できないコードは、それ自体が自己説明的ではないということです。

良いコードとは、関数名や変数名、処理構造だけで意図が明確に伝わるものです。コメントは“なぜそうしたか”という背景や、例外的な事情を説明する最終手段に限るべきです。

認知心理学的に見て短いコードは理解しやすい

人間の作業記憶（ワーキングメモリ）は非常に限られており、一度に保持できる情報量はせいぜい7±2個だとされています。つまり、100行以上の関数や複雑にネストした処理は、人間の脳が同時に把握できる範囲を超えているのです。

短い関数や小さなモジュールであれば、1画面で全体を見渡すことができ、因果関係を一目で理解できます。コメントを多く書いても、読者は文章読解モードに切り替わるため、コード全体の構造理解が中断されます。

短く、単一責任原則（SRP）に従って分割された関数こそが、人間の認知特性に適した形なのです。

コメントは腐るが、短いコードは腐らない

時間の経過とともにコメントは更新されず、コードだけが修正されていくという現象は誰もが経験しています。これにより、コメントと実際の挙動が食い違い、保守作業者を混乱させる原因になります。

特に古いコメントが残っている場合、「コメントを信じた人」がバグを生むという事態すら発生します。これは静的解析では検出できない、人為的な不整合です。

一方、短いコードは構造そのものがドキュメントであり、修正しても意図が保たれやすく、コメントのように情報が腐敗することがありません。短いコードとは、自己修復的なドキュメントなのです。

デザインパターンはコメントの代わりに思想を表す言語である

短いコードが強い理由は、行数が少ないことに加えて「設計思想を共有するための共通言語」として機能する点にあります。デザインパターン（Strategy、Observer、Factoryなど）は、開発者がコードを見ただけで意図を即座に理解できるようにする “圧縮された知識” です。

コメントで「このクラスは状態変化を監視する仕組みです」と書く代わりに、Observerパターンの構造を採用するだけで意図が共有できます。これは、コードが“説明文”ではなく “記号化された思想” として機能しているということです。

AI時代では短いコードが圧倒的に解析しやすい

AIがコードを理解する時代において、短いコードは機械にとっても非常に扱いやすい形です。AIはテキストをトークン単位で処理します。長い関数や冗長なコメントが多い場合、トークン数が増え、モデルの注意リソースが分散してしまいます。その結果、AIの推論が曖昧になり、誤修正が発生しやすくなります。

短い関数であれば、AIはその構造全体をコンテキストとして保持しながら、正確に目的と副作用を把握できます。AIにとって短いモジュールは “再利用可能な思考の粒” であり、人間がモジュール設計を通じて理解を促進するのと同じように、AIも短い構造で精度を上げていくのです。

コメントで説明できるなら、それは構造で表現できる

「この関数は○○を行います」とコメントに書くよりも、関数名を calculateChecksum() のようにするほうが明確です。「この部分はバグ回避です」と書くよりも、applyLegacyWorkaround() と名付けるほうが伝わりやすいのです。

つまり、コメントで説明できることは、命名や構造で表現できるということです。構造と命名に思考を込めれば、コメントはほとんど不要になります。コメントを書くより、コードそのものを明快にする努力を優先すべきです。

ソースを短くすることは思考を構造化すること

ソースを短くするというのは、単に行数を削減することではありません。「この処理は何のためにあるのか」「この関数の責務は1つか」という問いを繰り返す過程で、思考そのものを整理し、構造化していく行為です。

長いコードはしばしば思考の流れをそのまま書き写した “作文” です。短いコードは、思考を整理して論理的に再構築した “設計図” です。コードを短く保つということは、単に技術的な工夫ではなく、思考の密度を高める知的訓練なのです。

コメント主義から構造主義へ

過去の開発文化は、「人間は誤るものだから、それを補うためにコメントを残そう」という発想でした。しかし現代の開発文化は逆です。**「人間は誤るものだから、誤りにくい構造を設計しよう」**という考え方です。

これは、アンクルボブやデイブ・トーマスらが『Clean Code』や『The Pragmatic Programmer』で繰り返し強調した考え方と一致します。コメントを書くことは安全策ではなく、構造化できていないことの兆候です。短いコードを書くというのは、説明文ではなく論理構造で語るという態度の表れです。

まとめ

コメントは一見親切そうに見えて、しばしば理解を妨げ、時間とともに劣化していきます。一方で短いコードは、構造的に自己完結しており、変更にも強く、AIが解析しやすいという点でも圧倒的に優れています。

つまり、「ソースコメントを残すよりソースを短くする方が10倍良い」のは、短いコードが人間と機械の双方にとって最も理解しやすい形式だからです。

コードは説明文ではなく、意図と構造を表現する言語です。コメントは思考の代わりではなく、思考の痕跡として最小限にとどめるべきです。コードを短く保ち、構造で語ることこそが、現代のソフトウェア開発における最高のドキュメントであり、最も誠実なコミュニケーションなのです。