ソースコードにコメントを書くかどうか
プログラムにコメント書かない文化もあるよって話 - NZ MoyaSystem
一部同意できる部分もあるのだけども、やっぱりある程度コメントは書いたほうが良いと思う。書きすぎはよくないが。
自分が書いたほうが良いと思うのは以下の部分かな
- 公開している関数/定数
- 複雑なアルゴリズムを実装している部分
- なぜこのコードなのかを書いたほうが良い部分
- 外部ライブラリのバグなどで、おかしなコードになっているけど正しいコード
- ある仕様に決めたけども、いろいろ議論がありうるもの
「なぜ」の部分も書いてもらった方が、仕様を変えるかどうか迷った時に参考になる。
きれいなコードを書けばコメント書かなくても良いという意見だけども、そもそもその綺麗さにはプログラミング言語/ライブラリで書けることという限界値があって、現在のプログラミング言語/ライブラリはそこまで完璧なものだとは思っていない。ので、どうしてもコメント書かないとわからない部分がでてくるよなと。
また、読む側の視点がぬけているよね。コメントはあったほうが読む速度があがるだろうし、邪魔にならない程度ならばあった方が良いだろう。ある程度のコードを読む能力が高い人を常に確保できるのであれば省略しても良いけど現実は結構難しい。書く側がこれぐらい読めるよと思っていても、それは常に読んでいるからバイアスがかかっていて、読む側は内心文句言いながら読んでいるかもしれない。
あと気になった部分。
プログラムの仕様書にあたるドキュメントについては、詳細かつ簡潔（1チームにつき Word 数十ページ程度）にまとまったものが共有されており、仕様変更が発生した場合には随時メンテナンスが入っています。コーディング担当者がメンテを忘れても、レビュー時にたいてい誰かが指摘してくれるので、メンテナンス漏れが起きることは少ないです。
仕様書のメンテナンスコストがコメントのメンテナンスコストって同じじゃないのかな。どこに書くかが違うだけで。
結局コメント書いてるじゃんと思われるかもしれませんが、「なぜこの修正を行ったのか」「修正前後で動作がどう違うのか」などの情報は、プログラムそのものではなくコミットやチケットに付随する情報のため、プログラムのコメントとして残すのは不適切です。
「なぜこの修正を行ったのか」「修正前後で動作がどう違うか」はコミットログで良いと思うが、「現状なぜこのコードになっているのか」はソースコードに書くべき話かな。
