Whyについてコメントを書きHowについてコメントを書かない

ソースコード中のコメントは、我々を助けてくれることもあれば毒になることもある。
よかれと思ってコメントをかいたことが、後からメンテナンスする人を苦しめることにもなる。

例えばコメントの情報が誤っていたり、わかりにくい表現でコメントされている・無駄にコメントを書きすぎているなどの場合、ノイズになってしまう。

コメントを書くというのは、とても繊細なことである。
ではコメントを書かないほうがいいのか？

否、コメントを全く書かないという場合も我々を苦しめることもある。
理想は、コメントを書かずにソースコードでコンテキストを伝えることだと思う。
しかし、それには限界があるので、コメントで伝えることになる。

我々の生産性を上げてくれるコメントとは、どのようなものか？

Whyについてコメントを書く

何か意図があり、あえてスタンダートな実装から外した場合、なぜ(Why)そのような実装をしているのかコメントが必要です。

経験が浅くてその手段しか思い浮かばなかったのか？特別な理由があってそうしているのか？が分からないからです。

そのような実装に出会った時、安心してリファクタリング出来ません。
Whyのコメントを書く意識がないのであれば、経験の浅いエンジニアだと私は思います。

例えば以下のものには、コメントをつけたほうがよいでしょう。

もし、富豪プログラミングをしているのであれば「リソース的に大丈夫であること」と「将来的にも大丈夫であること」の理由を書きましょう。
富豪プログラミングをしたほうが、理解しやすい設計になりメンテナンスしやすいと思います。

「富豪プログラミングをしても問題はないが、第三者が見た時に不安に感じそう」であれば、あえて富豪プログラミングをしているということをコメントに書きましましょう。

不十分な実装に対してもコメントが必要です。
不十分な実装の理由として、このようなものがあります。

不十分な実装の理由が、書けていれば大体OKだと思います。
本当は、このような設計にしたかったと理想の設計を書いてあればなお良しです。

そのコードが属するコミュニティ(会社など)で、常識とされるものであればコメントは不要です。
ただ、人によって常識の範囲にズレがあるのは仕方のない話です。

自分は普通だと思っていたことが、普通でないこともあります。
コードレビューをしてなぜ？と聞かれた場合は、コメントに書くか実装を修正しわかりやすくなるように努めましょう。

どのように(How)に計算するのかアルゴリズムの詳細をコメントに書く必要はありません。
例えば、フィボナッチ数を計算する関数があったとして、その計算手順についてコメントが書いているなど。

コードを読めば、アルゴリズムはわかります。
それよりも、何を計算したいのかをコメントに書きましょう。
興味があるのは、成し遂げたいことです。
コメントは、「フィボナッチ数を計算して返す」これだけでいいです。

Howについて書かれたコメントは、アルゴリズムに変更を加えた場合、コメントと実装が乖離します。
コメントと実装を合わせるために、コメントを修正するのは手間を産み、もしコメントを修正し忘れた場合は混乱の原因になります。

アルゴリズムではなく、何を実現したいのか？をコメントに書いたり、適切な関数名を名付けるようにしましょう。

コメントを書くことは、実際の実装と同じレベルで繊細で難しいです。
必要最低限で説明責任を果たすコメントが必要です。
コメントを書くのにも設計能力が必要です。

なるべくコメントに書かずにコードが語るようにするのが、bestです。
コードの誤りは自動テストで検知できますが、コメントの誤りは検知できません。

ですが、適切なコメントを書いていればとても価値があります。
長期間に渡って複数の人が触れるコードであれば、なおさらです。

コメントは、落とし穴があるから気をつけろよ！と仲間に知らせるためでもあり、正しい設計判断をしたということを説明するためでもあります。