コードコメントに書くべきは「意図」
2.トリッキーな実装
ソースコードのコメント率は20%を切ることが望ましい : 小野和俊のブログ
ソースを読んだだけではすぐにわからないようなアルゴリズムを採用している場合や、使用しているライブラリのバグ回避のための特殊な処理を行っている場合、または他の人が見たときや自分が数年後に見た時に「なぜここでこんなことを？」と感じる可能性がある場合にはソースコードにコメントを追加するべきだ。これは言わばトリッキーな実装である。
私はこの部分にはもうちょっと汎用的に「意図」を書くべき、とすることを提案しよう。*1
トリッキーな実装というのは、「普通」ということが分かっていて初めてトリッキーかが分かる。普通か、トリッキーか、というのは時代背景*2というかハード的な制約も関係するだろう。常識は移ろいゆく。本人がトリッキーではないと確信して書かれるコードと、トリッキーなコードとの線引きはどうしたらよいのだろう？
あるいは、プログラム初心者が書いたようなプログラムというのは、その本人が考え得た精一杯であって、普通とかトリッキーとか考えてる余裕なんぞこれっぽっちもない。そして、大抵はそのコードは未熟さゆえのトリッキーなものとなる。ならば、初心者は常にコメントを書くべきだろうか？書くとしたらどのようなコメントを？
つまるところ、ソースコードというのは機械が読んで実行するためのものなのだから、「どのように動くか」という事実については雄弁に語ってくれるものなのだけど、「どのような意図で書かれたか」ということについては全くもって寡黙だ。
ならば、コード中にプログラム言語ではない自然言語を敢えて書く理由は、その欠けている「意図」を補うためだ。
他人のコードをデバッグしていて助かるのは、事実を補佐するコメントなどよりも、何をしようとしたかという「意図」だ。過去にそれを記述した人の「意図」を解することができたなら、そのコードをどのように直せば良いのかが決めやすい。他人のコードをリファクタリングする場合もそうだ。初心者のコードでも、意図が書かれているならレビューは容易に行える。意図不明のコードほど手に負えないものはない。*3
しかし、コード中のコメントにうまく「意図」を織り込めている人は少ない。なので、ソースの記述の断片からプログラマは意図を読み取ろうとする。*4そのコードは若さゆえの過ちでトリッキーに書かれているのか、何か特別な意図があるのか。用途が途中で変わったのだろう変数の命名の直し忘れ、過去の処理フローやデータ構造に引きずられたのであろう条件分岐や繰り返し。そういったものからミスによってすっきりしない形になっているのか、何らかの意図があったのかを推し量る。
Comment that has puzzled you or tricked you.
404 Blog Not Found:コメント!=ドキュメント
あなたが迷ったり勘違いしたところをコメントせよ
この格言も「意図」を書く教えだ。特に迷ったところ、勘違いしたところには「意図」を書こう。後からソースを読んだ人が格段に作業しやすくなる。そして、後からソースを読んでありがたく思い感謝することになる人というのは多くの場合、自分自身だ。
*1:「1.公開されるAPI」についてはJavaならjavadocを用いればよいと思う。そしてステップ数換算での「コメント率」という数字はおおよそ当てにならないと考えている。
*2:直線描画のブレゼンハムアルゴリズムは過去には普通であったが、現在では浮動小数演算してしまえばいい。ブレゼンハムのようなトリッキーなことをすると分岐予測を外しまくる。が、パイプラインなどという概念がなかった時代にはトリッキーでもなんでもなかった。
*3:そして触らぬ神に祟りなし、と放置されるか、参照箇所がないことを調べてからざっくり削除するかのいずれかの運命を歩む。
*4:この部分についてはリファクタリングとヒステリシス - カタチづくりの考察が面白い。これに対する私の過去の考察はソースコードの内側 - プログラマーの脳みそ
