プログラムを開発する際、動作の仕様や仕組みなどをコードにコメントとして記載します。
このコメントについては、エンジニア同士でも、書く、書かないで意見が分かれることが多く、絶対の正解と言えるようなわかりやすいものはないと思います。
今回は、私自身の経験を踏まえて、コメントについて、改めて考えてみようと思います。
コメントは書くべきか？
まずはじめに、私個人の結論を述べさせていただくと、基本的にコメントは書くべきだと考えています。
コードを書く際に、原則として、「読んでも理解できないようなコード」を書かないのは、当たり前にすべきことだと思います。
読めばわかるのに、わざわざわかることをコメントに残す意味があるのか。
当然、このように考える方もいることでしょう。
たしかに、コードを読めばわかることであれば、コメントがなくても、コードを読んで理解することができますから、コードを読んでもわからないようなことにだけコメントを残せばいい、そのように考えることも至極当たり前のことだと思います。
読めばわかる場合でも書くべきコメント
上述したように、「読んでも理解できないようなコード」や実装の裏に何かしらの事情や経緯などがない限りにおいては、コードを読めば、大抵のことはわかるでしょう。
理想を言えば、コードは、コメントなど一切書かなくても、誰が読んでもすぐに理解できる状態であるべきだと思います。
コードを読んでわかることにはコメントせず、読んでもわからないことにだけコメントするべきである。
結果として、このような考えも自然なことだと思います。私自身も、この考え方が間違っているとは考えていません。
ですが、現実的なところでは、これだけでは、不十分であると考えています。
コードを読むという行為は、単純な文章を読むのとは違い、使用されている変数がどのような状態になるか、どこから呼び出され、どのような入力が入ってくるか、条件分岐によって、どのように処理が変化するかなど、色々な要素を考慮する必要があります。
必然的に、読む際のコストは、単純な文章に比べて相応に高いものとなりますし、量が増えれば増えるだけ、比例的に増加していくことになります。
これは、コードの保守性というだけでなく、効率や生産性の観点から見ても、あまり望ましいとは言えないと思うからです。
実際にコードを書く際、大抵の場合は、機能の概要がわかっていれば、問題がないことがほとんどだと思います。
最もわかりやすい事例を上げるとすれば、ライブラリの機能を使う場合を想像していただくのが良いかと思います。
リファレンスを見れば、どんなクラスや機能で、使用可能な変数やメソッドについて、説明が記載されていますから、それを見て、十分に利用が可能でしょう。
その際に、内部の詳細な実装を確認しなければいけないような事態は、まずありえないと言って差し支えないかと思います。
つまり、コードを書く際に、コードを詳細に読み込むことは、必ずしも必要ないということになります。
従って、読めばわかるようなコードであっても、必要以上にコードを読み込むコストを減らすことができるため、変数やメソッドには、コメントを書くべきであると考えます。
書くべきではないコメント
すでに述べたように、メソッドや変数にはコメントすべきだと考えていますが、同時に、コードを読む前提であれば、読んでわかることに逐一コメントをするのは冗長だとも考えています。
例えば、このような処理があったとします。
if (value < threshold)
{
value = 0.0f;
}
この処理に対して、以下のようなコメントをしたとしましょう。
// しきい値未満の場合は、値を 0 にする
if (value < threshold)
{
value = 0.0f;
}
これでは、処理を直訳しただけですし、ある程度、経験のあるエンジニアであれば、単純文章を読むのと、読み解くコストは変わらないでしょう。
条件が大量に列挙されているため、補助的に記載しておく、などの使い方であれば、直訳のコメントでもあった方がわかりやすい場合もありますが、これは、比較的稀なケースでしょう。
それだけ条件が増えているなら、メソッドを分けるなどの対応をした方がベターでしょうし、分けないほうがいいような状況は少ないからです。
また、このようなコメントが増えると、本当に重要なコメントが埋もれてしまって、伝えなければならない情報が、正しく伝わらなくなる可能性もあります。
絶対に書かなければいけないコメント
ここまでは、書くべきかどうか、という話でしたが、中には、絶対に書かなければならないコメントというものも存在します。
書くべきではないコメントの際の処理を例に考えてみましょう。
if (value < threshold)
{
value = 0.0f;
}
この処理は、しきい値未満を 0 にするという処理ですが、この処理を行っていることに、コード上からは読み取れないような意図が存在している場合、この処理を変更されたり、削除されたりした場合に、動作に深刻な影響を及ぼす危険性が生まれます。
// しきい値を下回る値で処理をした場合、数値が小さすぎて、正しい計算ができなくなるため、
// 0 として扱って、計算結果に影響が出ないようにする
if (value < threshold)
{
value = 0.0f;
}
例えば、このような意図があった場合、この処理を一見して不要と判断して削除した場合、正しい結果を得られなくなってしまいます。
今回の例は、比較的わかりやすい内容ですので、消したとしても、後に実行して、処理の意味に気づくこともできるかと思います。しかし、複数要素が絡み合った煩雑な処理などで、こうした状況に陥ってしまうと、「理屈はわからないけど、この処理を消すと動かなくなる」といった地獄のようなコメントが後に生まれてしまうことになります。
ですので、処理に明確な意図や経緯があり、それがコード上から読み取れない場合は、必ずコメントを書くようにしましょう。
コメントを書く際のポイント
最後に、コメントを書く際に、どういった観点に気をつけてコメントを書くべきかを考えたいと思います。
基本的に、コメントは、自分以外の他人のためのものです。そのため、自分だけがわかるようなコメントでは、全く意味がありません。
実装を行った自分自身は、すべての情報を持っているため、わかりきったようなことでも、情報を持たない他人には、それを知るすべは、コードしかありません。
ですので、相手が知らない情報を考慮した上で、長くなりすぎないように、かつ、必要な情報が欠損しないように気を配る必要があります。
情報量の目安については、ライブラリのリファレンスなどを参考にするとよいかと思います。
また、未来の自分も他人です。自分で実装したコードであっても、時間が経てば、記憶は薄れますし、細かい意図などは思い出せなく鳴っている可能性もあります。
そうなった際に、コメントを正しく書いていない過去の自分を恨んでも、後の祭りですので、必要な情報を精査して、きちんと書き残すように習慣を付けることが未来の自分のためになるかもしれません。