【PHP】コメントを書く際に注意すること #PHP

前回は、「コメントを書くべきか、書かないべきか」について述べましたが、
今回は、「コメントを書く際の注意点」について、
自分なりの意見を書いてみたいと思います。

コメントを書く際に一番重要視していること

大事なことは

です。
可能であれば、と書いたのは
具体性を出すことで冗長になってしまったり、
わかりづらくなってしまったりするのであれば、
それを避けた方がいいからです。

例：


// 注文商品の中に特定のメーカーがないか確認する
if ($order->hasHogeProducts()) {
    return;
}

「確認」はソースを理解するための言葉としては、ほとんど何の意味も持ちません。
どのように確認するのか、確認したら何をするのか、といった情報の方が大切です。

また「特定の」ではなく、具体性を持たせられるなら（短くまとめられるなら）
具体的に書いてしまっていいと思います。


// 注文商品の中にメーカーがHogeのものがあれば処理しない
if ($order->hasHogeProducts()) {
    return;
}

抽象性を消すことができました。
でも、もう少し短く、端的にまとめられる気がします。


// メーカーがHogeの注文商品があれば処理しない
if ($order->hasHogeProducts()) {
    return;
}

できるだけ具体的に、そして短く。
これを第一に意識してコメントを書くようにしています。

すべてのコメントに対して、細部ひとつひとつを気にしていたらキリがないです。
だからこそ、意識して最初から精錬されたものが書けるようになることが大事。

そのためには、（時間があるときは）ソースを見直しながら推敲することも必要なのかなと思います。