出来事だけ書かれていると、「何で?」という疑問でモヤモヤする

他人が書いたソースコードを読んでいて、ふと思う。ソースコードにコメントを残すときにメソッドや一連の処理の前に、そこでどういう処理をしているのかということを書くのは誰でも良くやるけど、(極端に汚いコードを書いている場合は例外として)実はあんまり役にはたたないと思う。

なぜそういう処理をしているのか、なぜそういう実装になっているのかという理由やその背景が書かれていないと、コードだけ見てその意図を理解することが途端に難しくなる。処理の理由がわからないから、結果としてその箇所には手を入れられなくなってしまう。

ブログやツイートのように他人も読む文章はもちろんのこと、たとえ日記のように自分しか読まないものでもあっても同じことが言えると思う。例えばこういうことをした、あるいは誰々にひどい言葉を投げかけてしまった、などといった出来事やあるいはそこから思ったことだけが書かれていると「何で?」という疑問が解消されずに何だかモヤモヤする。

なまじ書いているときは背景などの記憶が鮮明のためついつい忘れがちだけど、ソースコードも文章も、なぜそう感じたのか、なぜそういう行動を取ったかという背景や理由を書き残しておかないと、いずれ行動の意味がわからなくなってしまう。