コメント

comment.png

良い(意味のある)コメント

ソースファイルについてのコメント

  1. ソースファイル内の宣言の共通点
  2. マニュアルの参照箇所
  3. メンテナンスのための一般的なヒント

各クラス、テンプレート、名前空間についてのコメント

  1. 関数の目的(javadocコメントなど)
  2. 使ってるアルゴリズム(見ればわかるような場合を除く)
  3. 環境に関連する前提条件

ここのグローバル、名前空間変数、定数についてのコメント

  1. わかりにくい部分
  2. 移植性を持たない部分

数値などのデータ

テストコード

テスト対象の関数に渡す引数の値や、検証のための値など。

不用意なコメントはなるべく減らそう!

  • あまりにも自明な内容

何が「あまりにも自明」かは人によって異なりますが、ここでは調べればわかる明白な事実と定義しましょう。
なぜいけないのか?
それは、そのあとソースコードを修正するときに、コメントの直し忘れが発生してしまうからです。
嘘コメントを生み出してしまうのです。
コメントはコンパイルでチェックできないので、コメントの直し忘れが発生してしまいます。
次の修正時に、コメントとソースコードの内容が違っていると、どちらが正しいかわからなくなるという事態を引き起こします。
コメントが書かなくても意図が伝わるようなコードを書くことを心がけよう。

対応表

C++,javascript,CSS,Objective-C,java python HTML
1行コメント //コメント #コメント
複数行コメント /*コメント*/ """ コメント """1 <!— コメント —>

サポートサイト Wikidot.com