この考えに至った経緯
コーディングをしている人で、小まめにコメントを残す人がいる。
がしかし、これは良い事だろうか？
確かに。ソースを読む時にコメントがあると、
処理の塊を判断しやすく、実装者の意図も汲み取りやすいメリットがある。
これは他の人に限らず、未来の実装者、自分に取っても同様の恩恵になるだろう。
私もそう思っていた。
しかし、ある熟練エンジニアの方とチーム開発をした際に、
その人は全くコメントを残さず、私は困惑した。
「この人は、他の実装者や未来の自分がコードを読み返すことを考えていないのか？」と。
しかしこの方は、かなりのレベルのエンジニアで数十年のエンジニア歴があり、
収入も私の３～４倍はあるだろうと言われるほど、社長や、社内・社外からの絶対の信頼を持つ方だ。
この方が意味もなくコメントを残さないなんてありえない。私はそう思った。
さらにはズボラな私よりも、性格的にもきっちりした方だ。
ここで一つの疑問を持った。
もしかして私の中の常識である、
「コメントはマメに書いた方が良いという、自分の中の常識が間違っている？」
私はその方を真似して、真意を探ることにした。
そして、2か月ほど共にチーム開発をしてみて、以下のメリットがあることに気が付いた。
コメントを書かないメリット
適当な変数名を付けれなくなる
当たり前だがコメントが無い以上、処理の意図を判断する材料は純粋なコードのみになる。
エンジニアの皆様なら分かるだろうが、コメントはコードに置いて重要な判断材料だ。
今まで、意図の重みをコメントと分散してきたものを、変数名だけで賄う必要があるので、妥協が許されなくなる。この結果、無意識的に具体的な命名をするようになる。
コードリーディングが劇的に速くなる。
コメントを書かないベテランエンジニアは他人のコードであっても、処理を理解するのが異常にはやい。
単なる経験歴によるものかもしれないが、それにしてもこんなにはやい事あるか？と思う程だ。
私は一つの仮説を立ててみた。
「処理の意図を理解するたに、今までコメントに頼ってきた時間がコードリーディングに当てられる。その結果リーディングのスピードもはやくなるのでは？」
その仮説は恐らく正しく、
個人の間隔的に、リーディング速度は1.3倍くらいになったと感じるかつ、
コードを追う時に心理的なハードルもかなり下がったように感じる。
意味の無いコメントを考える時間が無くなり、価値の高いコーディングをする時間が増える
皆さんはこんな事を思った事がないだろうか。
「コメントを読んでみたけど、よく分からなかった。もしくは、曖昧で色々な解釈があるがどれだろうか？」
私はこのようなコメントは、意味のないコメントだと思う。
全く枠割を果たしていないし、そういったコメントはよく分からないため、永続的に放置され、よく分からないまま残り続ける。
ここでまた問いだが、
「あなたは読解力と、説明する力にどの程度自身がありますか？」
もしここであなたが、どちらも100点満点だと答えたあなたでさえ、
コメントを書くには不十分だろう。
何故ならば、例えあなたが満点でも、他の人をそうではないからだ。
もしあなたが完ぺきなコメントを残したとしても、他の方が意図を読み取れるとは限らないし、
最悪、間違った解釈をして実装をするかもしれない。
寧ろ混乱を招く要因であり、これは間違った解釈に繋がりうる、バグの種だ。
そう言った上記のような、
意味もなく、寧ろ妨げになるコメントを考える時間を
変数名命名を考える時間時間に当てられるため、価値のあるコードが増えるだろう。
バグの発見が容易になる
コードにコメントがあるとついつい読んでしまうが、
もしかしたら、それは読んではいけないものかもしれない可能性がある。
それでもコメントは残すべきでは？という方へ
私もコメントを0にしろと言いたい訳ではないし、タイトルを吟味して欲しい。
要は、安易にコメントするべきではないと言いたいのだ。
現に私が参考にしたベテランの方も、0というわけでは無く。
非常に少ないというところに収まっているであろう。
コメントを残す場所は、私も完全に解を出せていないが、
時点での候補を挙げて見たいと思う。
クラスや関数に残す
コメントを残すべきだと言うような、複雑なロジックは
そもそもの設計が間違っている可能性がある。
そういったものは、クラスや関数に切り出し、
クラス・関数、引数の命名を熟考するべきだろう。
また、引数レベルの極小の対象はコメントを残してもよいが、
出来れば、型情報レベルに留めて欲しいと思う。
API・ミドルウェアレベルのバグに関する事
こういった、コードだけでは追えない、APIやミドルウェアレベルのバグはコメントを残すべきだ。
例として、
mysqlのバグで、同じ関数を2回連続して呼ぶ必要があるといった事を目にしたことがあるが、
もしこれに、コメントが無かった場合、私は冗長だと判断し片方を消してしまったかもしれない。