エンジニアのひよこ_level10

毎日更新してた人。たまに記事書きます。

コードだけでなく、コメントの2重管理も気をつけるべき【165日目】

コメントも2重管理に気をつけるべき

// おすすめ商品を5個表示する
$this->recommendItems();

こんなコメント。なぜダメか。

1.recommendItemsのコードを読めばいい。

例えば元コードに

// おすすめ商品を5個表示する
function recommendItems() {
    ....
}

なんて書いてたら、同じコメントを2つ書いていることになる。

2.recommendItemsの仕様が変わったら?

// おすすめ商品を10個表示する
function recommendItems() {
    ....
}

もしrecommendItemsの仕様が変わって、10個表示することになったら?

// おすすめ商品を5個表示する
$this->recommendItems();

こちらのコメントも書き換えないといけない。
後で見た人があれ?ってなってしまう。

recommendItemsの仕様変更なのに、別の場所のコメントまで書き換えないといけない。

コメントも、コードの一部。

コメントを書く時も、そのコメントがどこに影響するか。
今後見る人が本当に理解しやすいかなど、
結構神経を使うべきものなので、
コメントを書く時も、さらさらっと書かずに、これで本当にいいかな?と立ち止まってみてみましょう。