ぼくのかんがえたさいきょうのコメント

まず大前提なんですが、個人的には「不要なコメントは書くべきではない」と思ってます。なので、若干とんちっぽくて煙に巻いてる感があるかも知れませんが、僕が最高と思うコメントは「コメントを書かないこと」「コメントなしで一目瞭然のコードを書くこと」です…！

当然、一目瞭然のコードが毎回書けるわけではないので、そのときはコメントを書く必要があると思うのですが、

1. コメントの内容が正しい

2. コメントがなにを説明しているのかが一目瞭然である(What)

3. コメントがなぜここに書かれたのかが一目瞭然である(Why)

の3つがあれば最高のコメントかなと思います。

1について:

これは当たり前っぽいですが、関数の引数と返り値の説明をしているコメントが実装と違っていたりするケースもあるので

2について:

コードを読んでいてコメントに遭遇し、かつコメントがなにを説明しているのか一目瞭然ではないときは「どういう意図でこのコメント書いたんだろう？」ということを考えてしまうので、意味のないコメントや意味がわからないコメントはコードを読むときに負担になるので書かない方がよいと思っています！

3について:

「あなたが考える最高のコメントってなんですか?」という質問への回答なので、冒頭、「とんちっぽくて煙に巻いてる感」というエクスキューズがある。