コメントも2重管理に気をつけるべき
// おすすめ商品を5個表示する $this->recommendItems();
こんなコメント。なぜダメか。
1.recommendItemsのコードを読めばいい。
例えば元コードに
// おすすめ商品を5個表示する function recommendItems() { .... }
なんて書いてたら、同じコメントを2つ書いていることになる。
2.recommendItemsの仕様が変わったら?
// おすすめ商品を10個表示する function recommendItems() { .... }
もしrecommendItemsの仕様が変わって、10個表示することになったら?
// おすすめ商品を5個表示する $this->recommendItems();
こちらのコメントも書き換えないといけない。
後で見た人があれ?ってなってしまう。
recommendItemsの仕様変更なのに、別の場所のコメントまで書き換えないといけない。
コメントも、コードの一部。
コメントを書く時も、そのコメントがどこに影響するか。
今後見る人が本当に理解しやすいかなど、
結構神経を使うべきものなので、
コメントを書く時も、さらさらっと書かずに、これで本当にいいかな?と立ち止まってみてみましょう。