勝手に情報が古くなるコメントは不要

コメントが書かれている箇所と関係ない場所に修正が入ることによって、情報が勝手に古くなってしまうようなコメントは無意味です。

例えば、メソッドの呼び元のクラス名やメソッド名が書かれていることがあります。

/**
 * (略)
 * このメソッドはhogeクラスから呼び出される
 */

 

呼び元のクラスが変わったり増えたりした瞬間、このコメントは嘘になってしまいます。

呼び元が増える度にこのコメントも一緒に直すのは現実的ではありませんし、このコメントの存在に気付いてすらもらえない可能性も十分あります。

そもそもオブジェクト指向的な観点で言うと、メソッドがどこで使われるかは意識すべきことではありません。

「どこから呼ばれたかに関係なく、必要なものさえ渡せば要求された結果を返す」というのが、オブジェクト指向におけるメソッドの基本です。

 

他に、たまに見かけるのが、「○○行目を参照」のように行数が入っているコメントです。

ちょっと修正が入れば行数なんて簡単に変わってしまいますし、今その行にある処理自体が削除されてしまう可能性もあります。

そうなると、このコメントはゴミコメントになってしまい、本来どんな説明を見せたかったのかも分からなくなってしまいます。

 

今後修正する誰かに、コメントに書かれている行数まで直してくれることを期待するのは無理というものです。

それに、わざわざ他の場所を読ませるのはコメントとしてどうかと思います。
行数が多少増えることなんか気にせず、きちんとコメントを書くべきです。




コメントを残す

メールアドレスが公開されることはありません。 * が付いている欄は必須項目です