Thoughts on Commenting | コメント観

2024年現在の自分のコメント観を簡単にまとめておく。すべて主観であり、客観的な事実に基づいたものではないです。過去に読んだ書籍・記事・（限られた個人の、偉そうなことを言えない）経験を元に書いています。文献の引用などはないです。

コメント観

• コメントとドキュメントコメントは可能な限り区別して考えるのがよい
  • 「コメント（1行・複数行）は少ない方がよいが、ドキュメントコメントはたくさん書いてよい」と考えるような人もたくさんいると思われるため
• コメントを書く書かない以前に、命名・（適切な）型定義・テストなどはソフトウェアエンジニアリングの基礎として行われるのがよい
  • ただし命名が十分であることは、コメントを不要にする理由にはならない
• コードを理解するための時間をコメントが短縮できるのなら書くのがよい
  • t_wadaさんのコメントには whyを書くという提案は賛成である一方、why以上に理解に至る時間を短縮できるのであればそれにこだわらくてよい
• コメントの保守はドキュメントの保守よりも簡単
  • 保守されていなさそうなコメントはそれを見つけた時点で無益なら消せばよい

こちらの記事にも似たようなことを書いています。

• OSSをやり始めて変わったコメントに対する考え方｜unvalley