今週のアイロベックス

保守にやさしいコメントを書く

  • 2010年8月30日
  • 西槇
  • nishimaki

プログラミングを行ううえで、プログラムソースにコメントを
記載するのは当たり前だと思います。
先日、過去のソースコードを見る機会があり、
なるほどと思うことがあったのでご紹介したいと思います。

１）使用している技術についての解説、リファレンスマニュアルへのURL等が記載してあった。
　 またそれを使用している理由等についてもコメントで述べられていた。
　
　 本来であれば、このようなことはドキュメントに記すべきだと思いますが、
　 ドキュメントが一切ない場合には、まずソースコードを見ることになります。
　
　 開発当初は、開発初期メンバーが絡んでいることが多く、
　 採用した技術を選定したメンバーがいるため、なぜそれが使われているのか？
　 なぜ他のものを採用しなかったか？
　 などその人に聞かなければわからないことが多々あります。
　
　 後で保守する身になって考え付く理由は、
　 「きっとそれが最適だと思ったんだろう」ぐらいしかわかりません。

　 実は、バージョンの組み合わせ、他のミドルウェアとの組み合わせにより
　 問題があったため、いろいろ検証した結果、現在使用しているものだけが
　 最終候補として残ったのかもしれません。
　 そのようなことが、後から保守する担当者が想像しうるでしょうか？

２）ロジックの理由、特別な書き方をしている理由が述べられていた。

　 ソースコードの書き方が、わざと無駄なことをしているように見受けられる場合でも、
　 実は重要な処理、何か問題を回避するための施策を行っていることがあります。
　 それなのに、保守・改善等を求められた際、「ここが無駄な処理しているな～」
　 という安易な考えで、無駄な処理を取ってしまったばかりに、
　 後々大問題になるといったことがあります。
　
　 これらを回避するためには、なぜそのような書き方をしているのかの、
　 理由（言い訳）を書いておくと後で、他の人がソースコードを見た際に、
　 「○○の問題があるから、仕方なくそうなっているんだな」と納得することができ、
　 安易に手を加えて大問題ということが避けられます。
　

逆に保守にやさしくないコメントをひとつだけ紹介します。
開発者の方であれば、間違いなく納得してくれると思いますが、
ウソが書いてあるコメントが本当に困ります。
コメントがウソなのか、コメントのとおりに実装しようとしたが
記述ミス、プログラムミスによりバグが混じっているのか、まったく見分けがつきません。

コメントには何をしているかと書くことも重要ですが、
なぜそうなっているのかを書いてくれたほうが開発者にとっては助かります。
何をしているかは、ソースコードを読める開発者であれば（普通読めますよね）
見ればわかることですから、書いてくれれば助かりますが、
ないことが致命的なことを招くわけではありません。


ちなみに弊社では、コメントを書くルールがコーディング規約で決まっており、
ソースチェックなども行っているので、コメントなしのプログラム等はありませんので
ご安心ください。
　

最新の記事

バックナンバー

株式会社アイロベックス
TEL : 03-6892-2526
システム開発や、その他アイロベックスへのお問い合わせこちらから
ページのトップ