📝
無駄なコメントが多いとなぜ読みにくいか
最近コードレビューをしているときにほぼ全ての行にコードと同等のコメントを記載されているコードに出会いました。
コメントの内容が間違っているわけではないけどとても読みにくかったため、なんで読みにくいんだろうと思ったので、個人的に思った見解をまとめておきます。
なぜ読みにくいか
だいぶ簡略化したものですが以下のように、関数内で複数処理があるかつ、ほぼ全ての行に直後の処理と同等（抽象化されていない）のコメントが記載されている状態でした。
（実際は関数内でもっと処理が続いている状況です）
function hoge() {
...
// 対象のID
const targetIds = [];
// 対象のIDをプッシュする
users.forEach(user => targetIds.push(user.id));
// 対象のIDを更新する
api.update(targetIds);
...
}
この処理を単純に読むと、対象となるIDを抽出してAPIを実行しているだけかと思います。
ただコメントが書かれていることで、ついついそちらをまず読んでしまいます。（英語苦手日本人なので英語なコードより日本語のほうがつい目がついちゃいますし）
結果的に一行の処理を読むのに常にコメントと実コードの二つを意味もなく読む必要がでてしまいます。
つまりは一行分の処理を読むたびに常に二倍の短期記憶やワーキングメモリを要することとなる認知不可の高いコードになっているのかと思いました。
短期記憶やマジックナンバーについての説明は省略しますので、ご存知ないかたは各自調べてみてください。
プログラマー脳読むのもおすすめです。
じゃあどうするか
散々語られていることですが、コメントは直後の処理をそのまま書くのではなく、なぜそうしたのかなど、直接コードだけでは表せない内容などを記載しておくとよいです。
またそもそもコメントを書かなくて良いように、処理毎に処理を分割することや、説明用変数を用いるなど、可能な限りコードを通して意図を伝えられるようにするべきかと思います。
Discussion