ノートの端の書き残し

UnityやらC#やら。設計が得意かもしれない。

コードのコメント

フワッとしたポエムです。

コードにコメントはそれなりに書いた方がいい

リーダブルコードなど、良いコードを書くテクニックとして、コメントに書くくらいならコードにその情報を載せろ、というものがあります。
それはその通りだと思いますが、それとコメントを省略していいこととは違うように思います。
コードを読んだところで、「本当にこの解釈で合っているのか?」と思うことはないでしょうか。
間違いを犯さない天才プログラマのコードなら全幅の信頼を置けるでしょうが、ほぼ全ての人間は間違いを犯します。で、人の流動が激しいような場所では大抵その尻拭いは他人がすることになるのですが、その際に「本当は何をしたかったのか?」がわからないととんでもない時間を持っていかれます。
つまり、コードの意図をコメントとして残すことは有意義だということです。

以下のような例でコメントを書きすぎるな、というようなことを言われます。

//ファイルをオープンする
using (StreamReader sr = new StreamReader(fileName, Encoding.GetEncoding("Shift_JIS")))
{
    text = sr.ReadToEnd();
}

確かにこれは要らないことが多いでしょうが、これは程度の問題です。 誰でも知ってるAPIを呼び出してるだけなので、まぁ間違えないだろうという共通認識があるから要らないのです。「コードの処理内容そのままだから要らない」わけではないと考えます。 例えばここがプロジェクト独自のメソッド呼び出しに変わったら、処理そのままでもコメントを書いてもいいんじゃないでしょうか。
コードを書くときは常に誤読の可能性に気を配り、誤読しそうだと思ったらコードを書き直し、そこで全力を尽くすけれど、それでもコードの修正だけで十分にできないと思ったらコメントも書く。
それでいいんじゃないかと思います。

コメントは読む人のため

コメントを書くかどうかの話が、何故か普遍的な話のように語られることがあります。でもそんなことは無いと思います。
コメントが必要かどうかの判断には、「誰が読むのか」という要素が必ず入ってくるはずです。
チーム開発ならチームメンバーを思い浮かべ、「この人が読んだときにこれで誤解なく伝わるだろうか?」そんなことを考えながら相手のためにコメントを書くのが大事なのではないでしょうか。 矜持とか主義とかそんなことはどうでもよくて、読む人のことを考えたコードファイルを作れるようにしたいところです。

追記) リーダブルコードを久々に(4年ぶり?くらい)読んでみると、しっかりこの辺のことは書いてありましたね…… プログラム学び初め以来に読み返しましたが、経験で学んだことのおおまかな内容は大体書かれててやっぱ良い本だなぁと改めて思いました。