Fight the Future

Java言語とJVM、そしてJavaエコシステム全般にまつわること

コメントには内容ではなく理由を書く

SimpleDateFormatで行う処理はsynchronizedされません。複数のスレッドから同時にこのクラスにアクセスされた場合、違う結果が返された、という障害が起りうるわけです。しかも再現が非常にムズい、修正者泣かせの障害でしょう。はい、わかりましたわかりました、元に戻します…。となったところで、戻した理由を書いていなかったら同じ過ちが繰り替えされる可能性は消えませんよね。少なくとも繰り替えさないようにコメントを残しておきましょう

まさに言いたかったことを言い表してくれてる。


こんな系のコメントがよくある。

// SQL
String sql = "select ...";

見りゃわかるって。こんなコメントはまったく必要ない。
そもそもソースの内容なんてソースを読めばわかるわけで、コメントに同じ内容をもう一度記述する必要はないし、無駄でもある。


さらに言うと、この場合ソースを変えればコメントも変えないといけないときも多い。
そういうときに同じ内容を書くのは面倒なので、コメントはそのままなんてことも多い。
これでコメントとソースが一致しない、なんて状況が生まれてしまい、コメントはより悪者になる。


でもこれには僕も含めたプログラミング講師にも非があって、プログラミングを教える際に「コメントは何でもいいので書きましょう」的なことを言ってしまいがち。
これが職業プログラマにおける無駄なコメントの温床になってるのかもしれない。


コメントは何でもたくさん書けばいいってものでもなくて、無駄なコメントはソースを読みにくくするし、コメントを書かなくても読みやすいコード、が最高だと思う。


コメントにはそのソースを書いた「理由」がほしい。
あんまりいい例が浮かばないけど、なぜそこでnullを代入したのか、なぜこのcase文にはdefaultがないのか、とかいう理由こそコメントにしてほしい。


僕も仕事でのプログラミングでは、特にその点に留意して「理由」をコメントにするようにしている。
逆に無駄なコメントはしないように気をつけてる。