【ITニュース解説】Writing Code That Doesn't Need Comments: The Matrix Approach

システムエンジニアを目指す初心者がプログラミングを学ぶ上で、コードに「コメント」を書き加えることは、一般的に推奨される習慣として知られている。コメントはコードの理解を助け、将来的にコードを読み返す際の助けになると考えられている。プログラムの複雑な部分や理解しにくい箇所に説明を加えることで、コードがより明確になると信じていた人も少なくないだろう。

しかし、コメントへの過度な依存は、特に他の人が書いた古いコード（レガシーサービス）を扱う際に問題となることがある。例えば、ある税金計算の関数に「プレミアムユーザーには10%割引を適用する」というコメントがあったとする。だが、実際のコードを確認すると、割引ではなく追加料金を課す処理が実装されていた、という状況に直面する可能性がある。このようなコメントとコードの内容が異なる場合、それがバグの原因となることが非常に多い。コメントの内容を信じてコードを読み進めると、間違った前提で問題を追求することになり、結果として実際のバグを見つけるまでに多大な時間を費やしてしまうことになる。この経験は、コードのコメントが常に正確であるとは限らないという事実を突きつける。もしコメントが時間と共に古くなったり、誤った情報になったり、あるいは完全に嘘になったりする可能性があるのなら、なぜコードの理解をコメントに頼り続ける必要があるのだろうか。コード自身がその動作や意図を明確に語ってくれるような書き方はないのだろうか、という疑問が生じる。

この疑問に対する解決策は、新しい技術や複雑な概念ではなく、プログラミングにおける基本的な「リファクタリング」の習慣、すなわちコードをより良い形に改善する手法の中に見出せる。それは、「コメントでコードの働きを説明しようとする代わりに、その説明をそのまま関数の名前や変数の名前にする」というアプローチである。

具体的に説明すると、コードのあるまとまりが特定の役割を持っていると感じ、その役割を説明するコメントを書こうと思ったとき、その代わりにそのコードブロックを独立した関数として切り出す。そして、その関数の名前が、まさにそのコードブロックの役割や意図を説明する言葉になるように命名するのだ。このようにコードを記述すると、メインの処理の流れはまるで手順書を読むかのように明確になり、各部分が何をしているのかをコメントなしでも容易に理解できるようになる。

この手法が効果的である理由は、関数名や変数名といった「名前」が、プログラムにおいて不可欠な要素だからである。これらの名前は、コンパイラというプログラムがコードを処理する際にチェックされ、プログラムの構造の一部として扱われる。例えば、存在しない関数を呼び出そうとすれば、コンパイラがエラーを検出し、プログラマに知らせる。そしてさらに重要なことは、次にそのコードを読む人間にとって、その名前がコードの意図を正確に伝達する役割を果たすことである。適切に選ばれた名前は、そのコードの実装と常に一体であり、同期が取れている状態である。一方、コメントはコンパイラによって無視される単なるテキストに過ぎない。そのため、コードが変更されてもコメントが更新されずに残り、内容が古くなったり、誤った情報になったりしても、プログラムの動作には影響しないため、その不一致が見過ごされやすいという問題がある。

具体的なコード例でこの違いを確認しよう。例えば、商品の最終価格を計算する関数があり、以下のようなコメントが付いているとする。「季節割引を適用した後の最終価格を計算する」という関数の説明コメントがあり、その中に「冬の季節でメンバーの場合、15%オフにする」というコメントが付いた条件分岐がある。さらにその下には「割引を適用する」というコメントが付いて、計算処理が行われている。このコードはコメントによって動作を説明しようとしているが、季節の判定部分（例えば、月の数値による判定）は直感的ではなく、ビジネスルールが変更された場合には、このコメントがすぐに古くなり、誤った情報となる可能性がある。

このコードを自己文書化する形に書き換えると、理解しやすさが大きく向上する。まず、「現在の月が冬の季節に該当するかどうか」を判定するisWinterSeason()という独立した関数を作成する。この関数名を見れば、その関数が「冬の季節である場合に真を返す」という意図が明確にわかるため、内部の月の判定ロジックがあっても追加のコメントは不要になる。次に、「メンバーに対する冬の割引額」を計算するmemberWinterDiscount()という関数を作る。この関数名も、その機能そのものを明確に示している。そして、最終価格を計算するメインのgetFinalPrice()関数は、これらの新しい関数を用いて簡潔に記述される。「もし顧客がメンバーで、かつ現在が冬の季節であるならば、メンバー冬割引を適用し、そうでなければ割引はゼロとする。そして基本価格から計算された割引額を引く。」

この変更によって、コードの可読性は大きく改善される。まず、元の関数名getFinalPrice自体が「季節割引を適用した後の最終価格を計算する」というコメントの役割を担い、そのコメントは不要になる。季節の判定という具体的なロジックはisWinterSeason()という、その役割を明確に表す名前の関数の中にまとめられ、その名前自体が説明となっている。割引額の計算もmemberWinterDiscount()という自己説明的な関数に分離されている。結果として、メインのgetFinalPrice()関数は、一連の論理的な手順を述べるかのように自然に読めるようになる。例えば、マーケティング部門が将来的に「冬の割引期間を11月から2月に変更する」と決定した場合、修正が必要なのはisWinterSeason()関数の中だけで済む。かつて存在した季節判定の隣にあったコメントは最初から存在しないため、コメントが古くなったり、コードと矛盾したりする心配は全くなくなる。

この手法を実践する際には、いくつかの注意点がある。一つ目は、「過度に抽出しない」ことである。たった一行のコードのために関数を抽出しても、新しい関数名が元のコードよりも明確さや意図を増していなければ、かえってコードが複雑になる可能性がある。新しい関数名が、抽出されたコードブロックの役割をより適切に説明する場合にのみ、抽出は有効である。二つ目は、「古いコメントを残さない」ことだ。コードブロックを新しい関数に抽出し、その関数の名前が意図を明確に表現しているにもかかわらず、元の場所に古いコメントを残しておくと、コードを読む人を混乱させる原因となる。抽出作業が完了したら、古いコメントは速やかに削除すべきである。三つ目は、「不適切な命名をしない」ことである。例えば、calc()やdoStuff()のような抽象的で曖昧な名前は、コメントがない状態よりも情報量が少なく、コードの理解を妨げる。関数名や変数名は、その関数や変数が「何をするのか」「何を表すのか」という明確な意図を捉えるように慎重に選ばなければならない。

コメントに依存するのをやめ、関数名や変数名にその意図を語らせるようにコードを書くと、いくつかの重要な利点が得られる。第一に、「コードの可読性が大幅に向上する」。新しいチームメンバーがコードを読み解く際に、コード本体と説明が離れて配置されているコメントを行き来する必要がなくなるため、プログラムの全体の流れをスムーズに理解できるようになる。第二に、「リファクタリングがより安全になる」。関数名を変更する際には、コンパイラがその変更をチェックし、もしどこかでその関数が正しく呼び出されていなければエラーとして検出される。これにより、意図しない破壊的な変更が防止できる。一方で、コメントはコンパイラのチェック対象外であるため、コメントを修正する際には変更漏れや間違いがあっても検出されず、リスクが伴う。第三に、「ドキュメントが常にコードと同期するようになる」。コードそのものが説明の役割を果たすため、バグ修正や機能追加によってコードが変更されても、コメントだけが取り残されて古くなる心配がなくなる。第四に、見た目には意外かもしれないが、「書くコードの行数が結果的に減る」という効果もある。特定の機能を小さな関数に抽出することで、メインのルーチンはより高レベルな操作の羅列となり、視覚的な複雑さが減り、全体としてより簡潔な印象を与えるようになる。

システムエンジニアを目指す者として、この習慣を日々のプログラミングに取り入れてほしい。もしあなたの書いているコードに、あるブロックの働きを詳しく説明しているコメントがあれば、そのコメントを削除し、代わりにそのブロックを意図を明確に表す関数（または定数）として抽出し、コメントが語っていた内容をそのまま新しい関数の名前にしてみよう。この実践を通じて、あなたの書くプログラムがより読みやすく、保守しやすいものへと確実に変化していくのを実感できるはずだ。このアプローチによって、あなたのプログラムが常に明確で理解しやすい状態を保つことを期待する。