クリーンコードを目指すためのコメントの書き方ガイド

プログラムにコメントを書くのは大事とは言われていますが、なんでもかんでも書くのもダメです。以下のサイトで細かく内容は書いていますが、少々長い上に英語なので、簡単に説明します。

Best practices for writing code comments - Stack Overflow

1. コメントはコードを複製すべきではない

コメントは、コードの動作や目的についての追加情報を提供するものであり、コードを単に言い換えるためのものではありません。コメントを使って、コードの背後にある意図や、特定の実装が選ばれた理由を説明しましょう。

2. 良いコメントは不明瞭なコードを許容しない

コードは自己説明的であるべきです。コメントを多用することは、しばしばコードの不明瞭さを隠すために使われがちですが、そのような状況ではコード自体を改善するべきです。

3. クリアなコメントが書けない場合、コードに問題があるかもしれない

コメントを書くことが難しい、または書きにくい場合、それはコードに潜在的な問題がある可能性があります。コードが複雑であるか、ロジックが不明瞭である場合は、再検討やリファクタリングが必要かもしれません。

4. コメントは混乱を解消すべきで、引き起こしてはならない

コメントは、コードの理解を助け、読み手がスムーズにコードを読めるようにするためのものです。不必要に複雑なコメントや、誤解を招く可能性のあるコメントは避けましょう。

5. 非慣用的なコードにはコメントをつける

一般的ではないアプローチや、特定のコンテキストでのみ意味を成すコードには、その理由を説明するコメントを付けることが重要です。後でコードを見た人が、そのコードが存在する理由を理解できるようにしましょう。

6. コピーしたコードの元のソースへのリンクを提供する

オンラインで見つけたコードをそのまま使用する場合は、そのコードの出典や、元のソースへのリンクをコメントに含めることが望ましいです。これにより、コードの背景や信頼性を評価するのに役立ちます。

7. 外部参照へのリンクを適切な場所に含める

コードが特定のプロトコルやアルゴリズムに基づいている場合、関連するドキュメントや標準へのリンクをコメントに含めることで、そのコードの理解を助けることができます。

8. バグを修正する際にコメントを追加する

バグ修正を行う際には、その修正の理由や、問題が発生した背景についてのコメントを追加することが有益です。これにより、将来同様の問題を避けるための参考情報となります。

9. 不完全な実装をマークするためにコメントを使用する

開発プロセス中に、一時的な解決策を実装することがあります。そのような場合、コメントを使用してその事実を明記し、将来の改善が必要であることを示しましょう。

まとめ
プログラム内でのコメントの書き方は、コードの理解とメンテナンスを大きく改善することができます。これらのルールに従うことで、プログラマはより有益なコメントを書くことができ、結果としてコードの読みやすさとメンテナンス性が向上します。コメントはコードの一部として非常に重要な役割を果たし、適切に使用することで、プロジェクトの成功に貢献します。
コメントを書くのは大事ですが、せっかく書いたのに、「いらない」といわれるととても悲しいです。是非この機会にコメントの書き方を見直してはいかがでしょうか？