SQL徹底指南書の1−12に、他の言語はともかく、SQLはなるべくコメントを書くべきと言う記載がありました。
SQLでコメントを書くべき理由
本書にあった、SQLでコメントを書くべき理由は以下の通りです。
- SQLでは手続き言語ほど、コードそのもので語ることができないから
- SQLは実行デバッグができないから
これを読んで、なるほど、確かに! と思いました。
SQLは、なんでこのデータが必要なのか、なんでこんな変換をしているのかはコードでは表現できません。
またパフォーマンスの理由で、複雑な書き方をすることもあります。
こういった類は、コメントでしか伝えることができないと思います。
今後、SQLを書くことが多くなりそうなので、このことは心がけたいと思います。
開発言語のコメントは一長一短
一方、他の開発言語では、コメントの有無や書き方は、宗教論争になりがちです。
私は、コメントはあまり書かない派です。
主な理由は
- コメントのメンテナンスが大変。
- コメントとコードが一致しないことが出てきて混乱のもとになる。
- コメントがなくても、わかるコードを心がけるべき。
- バージョン管理のコメントがしっかりしていれば、ある程度追える
という考えからです。
ソースの中でパッと見何やっているかわからなかったり、イレギュラーな理由がある場合、TODOやFIXMEのコメントは書くべきだと思います。
ただ、javadocやpydocのようなクラスや関数ごとに、ズラズラとコメントを書くのは、できるだけ避けたいです。
しかし、そのコメントも一長一短だということは分かっています。短所は上記の通り負債になるということ。その考えでいけば、コメントというよりは、できるだけコードを書かないようにするべきということにもなりますが。
一方、大規模開発や人の出入りが激しい現場などは、コメントがあったほうがいいこともあるでしょう。
また、わがまま極まりないですが、そのコードを見るのが他人でなく未来の自分の場合は、コメントは念入りに書きたいです。
未来の自分は、コードを書いた理由は忘れていますが、コメントがあれば思い出しやすいです。
と、まあごちゃごちゃ書きましたが、バージョン管理やREADMEなどの記載がしっかりしてあれば、コメントは必要最低限にするべきかと思います。
まとめ
開発言語のコメントは最適解はないけど、SQLに関してはコメントを書くべき!