「何」よりも「なぜ」

なぜそのようなコードになったのか』を残すべきです。 
保守者が知りたいのは『なぜそのようなコードになったのか』です。既存のコードに手を入れて変更するにしても、セオリー通りではないコードは、なぜそうなっているのかが解らないと手を入れられません。一見すると冗長でバグがありそうなコードだけれど、もしかしたら複雑な理由があるのかも? そう考えたら迂闊には手を入れられません。『何をしているコードか』は、時間を掛ければ読み解くことができます。しかし、なぜそうやったのかは書いたプログラマーの頭の中にしかありませんから、コードから読み取ることはできません。だからこそコメントで補完する必要があるのです。更に、保守者への注意喚起まで残っていると素敵。
プログラムのコメントに『何をしているコードか』を書いても無意味なので、代わりに『なぜそのようなコードになったのか』を書くようにしよう - じゃがめブログ

まったく同感。
仕事でももともとあった仕事のやり方やルールを見直したいとき、なぜそういう風にしたのかが知りたい。
目的が同じで手段が違うだけなのか。
目的そのものが違うのか。


やっぱり「何」よりも「なぜ」だと思う。