可視性の高いコード

[リーダブルコード]コメント：情報密度の濃さ：正確に書く

なかなか面白いことを書いている。

もしも私がプログラマで、コードレビューでこのような指摘がでたらなかなか厳しいレビューアだなと思うだろうが確かにその通りである。行数カウンタなどの機能においてもこの観点は重要である。ただ、本来これは設計レベルの話でプログラマにそれをコメントする責任を負わせるのは酷かもしれないとは思うが。

だが、記事にもあるがそれは関数のヘッダコメントの話である。コード文中のコメントであれば長々と書くべきではない。長々と書かなければならないのであれば関数化しなければならない。コード文中のコメントを長々と書くとプログラムの可視性を著しく落とすのである。たとえ関数の中身が一行になろうとも関数化が必要だ。

また曖昧さはコード文中であろうと関数ヘッダコメントであろうと完全に除去せねばならない。下手に「エレガントな文章の方が分かりやすい」などと砕けた文章で格好つけたり、読み手に解釈を強いる曖昧さを残す文章にしては「絶対に」いけない。もしも曖昧なコメントがあれば冗長でもいいから正確に書くべきだ。そして必要なら関数化する。

このようにリファクタリングを行うと最終的にはコード文中からコメントがどんどん消えていく。コード文中のコメントが関数のヘッダコメントに変換されていくのである。結果可視性は向上していく。

「読める」コードにはそのような工夫が必要である。