先日初めてコードレビューをしていただけました。
その際コメントの書き方についての指摘が多かったので、指摘事項を備忘録としてまとめておきたいと思います。
はじめに
コメントを書く際の注意点については「プログラマが知るべき97のこと」にも掲載されています。
・コメントについてのコメント
・コードに書けないことのみをコメントにする
私はこのエッセイをレビューしていただいたコードを書き始める前に読んでいましたし、内容は頭の片隅に入っていたので、多少意識してコメントを書いていたつもりでした。
しかし、いざレビューを受けると、エッセイで紹介されているような駄目なコメントばかり書いてしまっていました。。
書いている最中は「これは必要なコメントだろう」と思って書いていたのですが、いざレビューを受けると、そのコメントのほとんどが「全く必要のない、むしろ邪魔にすら感じるコメント」になってしまっていたのです。
私の書いたコメントは「コードに書けないことのみをコメントにする」にもあった、「ノイズ」になっていました。
どこがいけなかったのか？
結論的には、コメントのほとんどが「自分のために書いたコメント」になっていました。
基本的に、自分の書いたコードやコメントを読むのは自分以外の他の誰かです（数週間後の自分かもしれませんが）
他の人が見てわかりやすいようなコメントを書かなければいけません。
そして、他の人が見て不要だなと感じるようなコメントは「書かないようにしなければいけません」
私の場合、実装が少し複雑になった部分には、数週間後に見返しても何をしているかがすぐに分かるように
「受け取った値を～し、hogeと結合して～、fooに～して渡す」
のようにして、長文で２行にもなるコメントを書いていました。
これは自分のためのコメントです。
そもそもコードを見て、何をしているのか考え込まなければいけないようなコードは改善しなければいけません。実際そのコードはコメントをつけなくても理解できる、すっきりとしたコードにできました。
私のようにプログラミングの経験が浅い初心者は、分かりやすく、丁寧なコメントを書こうと心がけます。
少しでも「理解しずらいかな？」と思ったコードにはコメントを書きがちです。
自分の学習用のコードならコメントをどれだけ書いても良いですが、上級者からすれば、コードを見れば理解できるような事をコメントで書かれると、うっとうしく感じると思います。
さらに、そのコメントの内容が間違っている可能性だってあります。
余計に混乱させてしまうことになり、それこそノイズになってしまうのです。
Docコメントの書き方
PHPDocについても指摘された点がありました。
コードを修正し、変数名の変更があった箇所のコメントを訂正し忘れていたり、例外処理があるのに@throws句を書き忘れていたり、引数の説明に動詞（〜を受け取る。などの動詞はいらない）を書いていたりと、、、
コメントが間違っていたり、コメントに無駄な説明があったりすると、むしろコメントが無い方がマシという状態になってしまうので
コメントの内容に誤りがないか？冗長になっていないか？書き漏れはないか？
細かい部分にも注意して書かなければいけません。
VSCodeのようなIDEで、PHPの組み込み関数を使う時、関数名にカーソルを持って行くとPHPDocが表示されます。
そこで引数の型や使い方を確認しますが、とても簡潔に書かれていて、その関数を使うために本当に必要な情報だけが書かれています。
urlをクリックして日本語のページを見てもそうで、関数の用途が簡潔に書かれています。
余計な情報が無いので、すぐに理解できて使えます。
私は自分の書いたPHPDocを見直して、同じように簡潔に書けていなかったので、改めて見直して不必要だと感じた部分は削除しました。
本当に必要な情報のみを残してあとは切り捨てるだけで、すっきりとしたコメントになり、文字数も減り、内容が頭にすんなりと入ってくるようになりました。
まとめ
コメントはできるだけ簡潔に、コードに書けないことのみを書く！！
コメントを通常のコードとまったく同じように考えて扱うことが重要になってきます。すべてのコメントを読む人にとって価値のあるものにし、そうでないものは即座に削除するか書き直すべきであるということです。
コードに「書いていないこと」ではなく、コードに「書けないこと」のみをコメントにするのです。