悪い」コメントに注意しよう(第11课).doc

「悪い」コメントに注意しよう 本文 ソフトウェアの受託開発や、オープンソースのプロジェクトでは、ソースコードが他の技術者の目に触れる。そのため、ソースコードから開発者の技術力が評価されやすい。 ソフトウェアの開発者は、モジュール分割やクラス設計には全力を傾ける。最近では、設計の完成度を高めるために、実装の後でリファクタリングを行うことも珍しくない。 だが、設計の良し悪しにこだわる開発者でも、ソースコードに書くコメントの品質までは、配慮が及ばないことが多い。コメントは本質的なものではないので、つい気を緩めてしまうのである。 ところが、開発者の希望に反して、ソースコードの読み手が印象を受けやすいのは、コメントの品質である。ソースコードから設計を読み解くのは容易ではないが、日本語や英語で書かれているコメントは目に付き安い。 優秀な技術者のっ書いたソースコードでも、驚くほど「悪い」コメントが書かれていることがある。そのようなソースコードを世に出せば、開発者の技術力にも疑問抱かせることになりかねない。 ここでは、「悪い」コメントとしてよく見られるパターンをいくうつか紹介する。 あなたがこれまでにリリースしたソースコードに、このようなコメントが残っていたとしたら、リリース前にコメントのレビューを行うことも、考えたほうが良いかもしれない。 自明 見れば分かることは、わざわざコメントとして書く必要はない。だが、自明なコメントは、実際のソースコードでは良く見かけるものだ。例えば、次のようなものである。 特に、プログラミングの初心者が書いたソースコードには、自明なコメントが大量に書かれていることがある。 自明なコメントは、無駄ではあるが、特に害をもたらすものではない。だが、あまりも多いと、初心者が書いていると思われ、顧客を不安にすることがありそうだ、 日本語訳 日本人のかいたソースコードには、ソースコードをそのまま日本語に訳しただけのコメント書かれていることが非常に多い。例えば、次のようなものである。 ソフトワェアの技術力と英語力は無関係だが、日本語訳のコメントが多く見られるのは、たいてい経験の浅い開発者のソースコードである。 日本語訳のコメントも、特に害をもたらづものではないが、あまりにも多いと、初心者が書いていると思われ、顧客を不安にすることがありそうだ。 記入漏れ ソフトワェアの受託開発では、ファイルや関数のヘッダを、提携フォーマットで記述することが多い。だが、実装が終わったリリースの前のソースコードを見ると、ヘッダ似書くべき内容がきちんと記入されていることはまれである。 記入漏れは、ソースコードのリリース野前にレビューを行えば防ぐことができる。逆に言えば、ヘッダ二記入漏れがあると、キチンレビューをしていない、と思われて染もうことになる。 不適切な名前の補足 ソースコードの可読性を高めるために、クラスや関数、変数の名前わかりやすることが重要である。しかし、まれに暗号のような名前をつけるプログラマーがいる。 不適切な名前のままでは本人も読めなくなるためか、暗号のような名前の意味をコメント出補っていることがある。たとえば、次のようなものである。 このような事例は、設計を行わずに闇雲にコーディングを行った場合に多く見られる。逆に、設計を重視するオグジェクト思考プログラミングでは、設計フェーズできちんとした名前がつけられるため、このような問題は発生しない。 ソースコードに、不適切な名前を細くするコメントがかかれていると、ソフトワェアの設計を行う技量がないと思われてしまうことになる。 嘘 ソースコードの誤りはコンパンレエラーやテストで検出できるが、コメントの誤りは気づかれにくい。そのため、たいていのソースコードには、誤った内容が書かれた嘘のコメント画少なからず存在する。 意識してコメントにうそを書く開発者はいない。それでも嘘のコメントができてしまうのには、いくつ理由がある。 コピー＆ペースト 似たような関数をまとめて作っている時や新しいクラスを作る時など、ゼロから書くのではなく、既存のソースコードをコピー＆ピーストした上で、それを修正することもある。その時、コメントだけを修正し忘れることが多い。 コメントのメンテナンス漏れ 機能追加などによりソースコードが書き換えられる際に、コメントを書き換えるのを忘れることが多い。 呼び出し先仕様変更 仕様変更や機能改善によって、ライブラリやコメポーネントの利用方法が変更になった時、変更したライブラリやンポーネントのソースコードだけでなく、それらを利用している箇所についても、コメントを書き直す必要が生じることがある。例えば、次のようなものである。 ここで、Ｒesteという関数の機能が改善され、引数にいろいろな値を