沖縄チームのキリです。タイトルは今携わってる案件のコード見た瞬間です。Gitは導入済みです。ここではコメントアウトとはコード変更で既存の処理部分をコメント化してコード上に残したものを指しています。
コードに残すコメントについては無限に記事が見つかる基本中の基本のことでわざわざ記事にすることでも無い気もしますが、自分なりの考えをまとめておきたいと思います。
実際に残っているコメントの例
変更になった処理がまるごと残っていること（コメントアウト）が多いです。これは修正箇所の検索をしようとすると大量の無関係なファイルにヒットして手間が倍増し、コードの見通しが非常に悪くなります。
以下その他の例（表現は少し変えています）
// 20XX-XX-XX (追加|変更)開始
...
追加されたコード
...
// 20XX-XX-XX (追加|削除)終了リファクタリングが非常にやりにくいです。
// (上|下|別ファイル)に移動じゃあここは消しといてください。
/**
* 変更履歴
* 20XX-XX-XX 〇〇に対応
* 20XX-YY-YY △△に対応
* 20XX-ZZ-ZZ □□に対応
*/変更履歴だけで画面が埋め尽くされています。知りたいのは今現在の仕様です。
// ◯◯の場合
// if (A) {
// if (B) {
if (C) {
...
}増えてくるとコメントがどの処理に向けたものなのかわからない状況が多発します。
上記のようなコメントが役に立つことはほとんどありません。むしろ害になり得ます。これらのようなコメントの変わりにGitを使ってコミットに残すだけで十分です。（ただしコミットの単位やコミットメッセージが適切でない場合はコミット履歴を探すときに苦労します…）
ダメなコメントはなんでダメ？
上で書いたように、ダメなコメントが残り続けるととにかく可読性が下がります。プログラミングはコードを書いている時間より読んでいる時間が多いです。そして不要なコメントは不要なコメントを誘発します。プロジェクトに新しく入ってきた人がコードを読み、変更の際は既存のコードをコメントアウトするという暗黙のルールができてしまいコメントアウトが膨れ上がることになるかもしれません。
/* 20XX-XX-XX ここから以下のコメントは無視して良い
* ここでの処理は◯◯を△△して□□を✕✕して…
...
* 20XX-XX-XX ここまででコメント終わり */プロジェクトがこのようなコメントだらけになったらどうでしょう？地獄でしかありませんね。
また可読性を上げるために不要なコメントを削除することになったとします。どこからどこまでが不要なコメントなのか、これは残しておいたほうがいいコメントなのか判断するためにはコードを解読しないといけません。そこに費やす時間は技術的負債となります。残すべきコメントを誤って削除してしまうことも発生するでしょう。
どのようなコメントを残すか
JavaDocやPHPDoc等の言語ごとのドキュメント記法、TODOのようなタグ、などエディターの恩恵を受けられるようなコメントは積極的に書くようにすると開発が捗ります。
他にはコードブロックで実現したいことをコメントで残すと良い、となにかの記事で読みました。例えばお釣りの計算で複雑な処理をしている場合（ここでは単純な処理を書きます）
...処理...
// 受け取った金額から商品の金額を差し引いたお釣りを返す
$change = $pay - $price;
...処理...のようになるでしょうか。実現したいことを書くことでコードが間違っていた場合でもここではどのような処理を書くべきなのかがわかりやすくなります。
あるいは1年後に自分がこのコードを読んだときに直ちに理解できるか？という視点でコメントを書くのもいいでしょう。自分の書いたコードの修正を忘れた頃に自分で担当することになって当時の自分を恨む、というのはままあることです。誰かのためにではなく自分のためにと考えると丁寧なコメントを書きたくなるかもしれません。
あまり意味のないコメント
人によってはあった方がいいのかもしれませんが以下のようなコメントはあまり意味がないので残す必要はないと思います。
// SUMにAとBを合算した値を代入する
$sum = $a + $b;// hogeの値を取得する
$hoge = getHoge();不要なコメントをできる限り減らすコーディング
基本的にはコードを読めば何を実現しようとしているのかがわかりやすいような変数名や関数名を名付けることを心がけるのがベストです。プログラミングにおいて命名は非常に重要なプロセスです。このあたりの話はまた別でしたいと思います。