コードに残す「コメント」について

コードを読みやすくしたり、コードからは読み取れない新しい情報をコメントとして残す。

コメントが経年劣化して、誤った情報になってしまったり、無駄なコメントが多すぎて逆に可読性が落ちてしまうという状況は避けたい。

チェックポイント

• 変数名、関数名をそのまま文章化したようなコメントになっていないか？
• 変数や関数の命名のわかりにくさをコメントで補おうとしていないか？
• ロジックの内部構造をなぞったようなコメントになっていないか？

コメントすべきこと、コメントする際のポイント

• 「定数がなぜその値になったのか」といった実装の背景をコメントで残す
• 他のエンジニアが見て疑問に思いそうなイレギュラーなポイントがあれば、コメントで説明
• 「それ」といった何を指しているのか誤解を招きうる代名詞のない簡潔で正確なコメントにする
• コードの意図は（実装の詳細から離れた）高レベルな説明にする
• 仕様変更の時に注意する必要のあるポイントにはコメントしておく

コメント不要論に関して

https://qiita.com/hiro-hori/items/1cf28a6ac75db077c8f3

こちらの記事のコメント欄がすごい白熱していて参考になる。

見た感じの結論だと「コメントは一つたりとも書くな」と言うわけではなくて、良いコメントは積極的に書いていこうということになると思う。やはりロジックの詳細をなぞっただけのコメントやコードを見ただけでわかるようなことが書いてあるコメントは不要であるが、このコードを書いた意図（特にwhy not）を残しておくのは大事そう。

まとめ

コメントとして残しておくこと

• 「なぜそうしたか」「なぜそうしなかった」という意思決定や背景
• 他のエンジニアが読んだら疑問に思うと想定されるポイント
• 仕様変更時の注意点

(今まであまりコメントを書いてこなかったので改めて勉強してみた、、、)