皆さんはソースコード上にコメントを書くだろうか？個人で開発していると // TODO などは書きがちだがチーム開発ではコメントはコードの意味を修飾する、もしくは経緯や歴史を示すものとして重要な要素となりえる。
コメントの良い書き方というのは CleanCode などで度々言論されているが実際に必要な箇所にコメントを書けるというのは特技であり、人類には早すぎると個人的に感じている。
コメントを何も書かない VS 意味のないコメントを書いてしまう
人類には2種類の人間がいると思っている*1。コメントを何も書かない人間と意味のないコメントを書いてしまう人間である。
コメントを書かないケースは本当に書かなくて論文から引用してきた計算式だけがあるというのを自分は見たことがある。このケースは初学者～熟練者まで多様に存在していると感じており、コーディング中にゾーンに突入したときに他のことが考えられなくなってしまうというケースが多い気がする。逆に意味のないコメントを書いてしまうのは初学者がやりがちで自分もよくやってしまうことがある。
どちらのケースでも実装する人からみたら特段問題はないが、別の人から見た場合や時間が立ってから改めて見た場合そのコードは古代文字*2となってしまう。これだとチーム開発をしている場合、後々の人が苦労するだけでなく最悪の場合フルリプレイスなどで余計な工数を取られてしまう。
じゃあ、どういうコメントがいいのか
CleanCode に書いてあるが正解だと自分は思っている。各自見てほしい。しかし、先程も行ったように実際にできるとは言っていない。
それまで、どうするのが良いのか？私は、とりあえず意味のないコメントも含めて一度書くのが良いと感じている。実装の経緯やどう実装しているか、特に複雑な計算式などにコメントを書いていく。そのあとに、必要なさそうなコメントを削る。削る判断はレビューに出してレビュアーに相談しても良い気がする。いわるゆ 書かないコメントより書く意味のないコメント である。情報量が0より1の方が良い。もちろん1以上あったほうが良い。
また、メソッドごとのコメントは必須で書くというルールにしてもいいかもしれない。メソッドごとに書くコメントは言語ごとに特殊な名前がついており、Python なら docstring、JavaScript なら JSDoc などである。これらのコメントは優秀な LSP であれば呼び出し側のメソッドにカーソルをあわせることでコメントの内容を表示できたりする。メソッドや関数は 単一責任の原則 が有名であり、この原則に則って実装されていればメソッドにコメントを書くことは容易かと思う。
レビュアーは気になりは気軽に投稿する
これまで、コードを書く人に焦点を当ててきたが私含め人類はそこまで賢くない。なので、必要な箇所でコメントを忘れるし、意味のないコメントも量産してしまう。そのなかで、レビュアーという立場は重要だと思う。自分以外の意見を取り入れ会話することで新たな発見をすることが多くある。なのでレビュアーは「実装した人はつよつよだからさっと見ればいいだろう」とか「忙しいから眺めるだけでいいか」ではなくちゃんとみて気になるところは素朴な疑問としてコメントするほうが良い。この疑問はソースコード内のコメントと同じ意味をなすことが多々とある。最近のエディタなどでは実装されたコードのPullRequest を見ることができ、私は、よくPRを見て経緯などを知ろうとするがここに自分の疑問がコメントされており、返信されていれば一瞬で解決できる。
まとめ
コメントはとりあえず書こう。
コラム
インターネットには「やらない善よりやる偽善」という格言がある。出典は2ちゃんねるで、湘南ゴミ拾いオフなどが例としてよく挙げられている。「書かないコメントより書く意味のないコメント」はこのパロディ
