技術

SQLはできるだけコメントを書くべき

SQL徹底指南書の1−12に、他の言語はともかく、SQLはなるべくコメントを書くべきと言う記載がありました。

SQLでコメントを書くべき理由

本書にあった、SQLでコメントを書くべき理由は以下の通りです。

  • SQLでは手続き言語ほど、コードそのもので語ることができないから
  • SQLは実行デバッグができないから

これを読んで、なるほど、確かに! と思いました。

SQLは、なんでこのデータが必要なのか、なんでこんな変換をしているのかはコードでは表現できません。

またパフォーマンスの理由で、複雑な書き方をすることもあります。

こういった類は、コメントでしか伝えることができないと思います。

今後、SQLを書くことが多くなりそうなので、このことは心がけたいと思います。

開発言語のコメントは一長一短

一方、他の開発言語では、コメントの有無や書き方は、宗教論争になりがちです。

私は、コメントはあまり書かない派です。

主な理由は

  • コメントのメンテナンスが大変。
  • コメントとコードが一致しないことが出てきて混乱のもとになる。
  • コメントがなくても、わかるコードを心がけるべき。
  • バージョン管理のコメントがしっかりしていれば、ある程度追える

という考えからです。

ソースの中でパッと見何やっているかわからなかったり、イレギュラーな理由がある場合、TODOやFIXMEのコメントは書くべきだと思います。

ただ、javadocやpydocのようなクラスや関数ごとに、ズラズラとコメントを書くのは、できるだけ避けたいです。

しかし、そのコメントも一長一短だということは分かっています。短所は上記の通り負債になるということ。その考えでいけば、コメントというよりは、できるだけコードを書かないようにするべきということにもなりますが。

一方、大規模開発や人の出入りが激しい現場などは、コメントがあったほうがいいこともあるでしょう。

また、わがまま極まりないですが、そのコードを見るのが他人でなく未来の自分の場合は、コメントは念入りに書きたいです。

未来の自分は、コードを書いた理由は忘れていますが、コメントがあれば思い出しやすいです。

と、まあごちゃごちゃ書きましたが、バージョン管理やREADMEなどの記載がしっかりしてあれば、コメントは必要最低限にするべきかと思います。

まとめ

開発言語のコメントは最適解はないけど、SQLに関してはコメントを書くべき!