悪いとは？/ セントラルファイナンス
[ 600] 技術者の評価を下げる「悪い」コメントに注意しよう
[引用サイト] http://www.aerith.net/design/comment-j.html
|
ソフトウェアの受託開発や、オープンソースのプロジェクトでは、ソースコードが他の技術者の目に触れる。そのため、ソースコードから開発者の技術力が評価されやすい。 ソフトウェアの開発者は、モジュール分割やクラス設計には全力を傾ける。最近では、設計の完成度を高めるために、実装の後でリファクタリングを行うことも珍しくない。 だが、設計の善し悪しにこだわる開発者でも、ソースコードに書くコメントの品質までは、配慮が及ばないことが多い。コメントは本質的なものではないので、つい気を緩めてしまうのである。 ところが、開発者の希望に反して、ソースコードの読み手が印象を受けやすいのは、コメントの品質である。ソースコードから設計を読み解くのは容易ではないが、日本語や英語で書かれているコメントは目に付きやすい。 優秀な技術者の書いたソースコードでも、驚くほど「悪い」コメントが書かれていることがある。そのようなソースコードを世に出せば、開発者の技術力にも疑問を抱かせることになりかねない。 貴方がこれまでにリリースしたソースコードに、このようなコメントが残っていたとしたら、リリース前にコメントのレビューを行うことも、考えた方が良いかもしれない。 見れば分かることは、わざわざコメントとして書く必要はない。だが、自明なコメントは、実際のソースコードでは良く見かけるものだ。例えば、次のようなものである。 自明なコメントは、無駄ではあるが、特に害をもたらすものではない。だが、あまりにも多いと、初心者が書いていると思われ、顧客を不安にすることがありそうだ。 日本人の書いたソースコードには、ソースコードをそのまま日本語に訳しただけのコメントが書かれていることが非常に多い。例えば、次のようなものである。 ソフトウェアの技術力と英語力は無関係だが、日本語訳のコメントが多く見られるのは、たいてい経験の浅い開発者のソースコードである。 日本語訳のコメントも、特に害をもたらすものではないが、あまりにも多いと、初心者が書いていると思われ、顧客を不安にすることがありそうだ。 ソフトウェアの受託開発では、ファイルや関数のヘッダを、定型フォーマットで記述することが多い。だが、実装が終わったリリース前のソースコードを見ると、ヘッダに書くべき内容がきちんと記入されていることは稀である。 記入漏れは、ソースコードのリリースの前にレビューを行えば防ぐことができる。逆に言えば、ヘッダに記入漏れがあると、きちんとレビューをしていない、と思われてしまうことになる。 ソースコードの可読性を高めるために、クラスや関数、変数の名前は分かりやすいものにすることが重要である。しかし、稀に暗号のような名前を付けるプログラマーがいる。 不適切な名前のままでは本人も読めなくなるためか、暗号のような名前の意味をコメントで補っていることがある。例えば、次のようなものである。 このような事例は、設計を行わずにやみくもにコーディングを行った場合に多く見られる。逆に、設計を重視するオブジェクト指向プログラミングでは、設計フェーズできちんとした名前が付けられるため、このような問題は発生しない。 ソースコードに、不適切な名前を補足するコメントが書かれていると、ソフトウェアの設計を行う技量がないと思われてしまうことになる。 ソースコードの誤りはコンパイルエラーやテストで検出できるが、コメントの誤りは気づかれにくい。そのため、たいていのソースコードには、誤った内容が書かれた嘘のコメントが少なからず存在する。 意識してコメントに嘘を書く開発者はいない。それでも嘘のコメントができてしまうのには、いくつか理由がある。 似たような関数をまとめて作っている時や、新しいクラスを作る時など、ゼロから書くのではなく、既存のソースコードをコピー＆ペーストした上で、それを修正することもある。その時、コメントだけを修正し忘れることが多い。 仕様変更や機能改善によって、ライブラリやコンポーネントの利用方法が変更になった時、変更したライブラリやコンポーネントのソースコードだけでなく、それらを利用している箇所についても、コメントを書き直す必要が生じることがある。例えば、次のようなものである。 嘘のコメントがあると、読み手はソースコードとコメントのどちらが正しいのか分からないことがある。コメントの方が正しいように見える場合は、ソースコードが誤っていると判断され、ソフトウェアの品質にも疑問を持たれることになる。 開発期間の長い大規模システムでは、実装に着手した時点でも、ソフトウェアの一部については、仕様がまだ未確定だったり、将来的に変更される予定になっていることがある。特に、最近主流となりつつある反復型の開発手法では、このようなケースも珍しくなくなった。 未確定な部分を実装する際、将来的に変更されることを、ソースコードにコメントとして書いておく開発者が意外に多い。例えば、次のようなものである。 ところが、最終的にリリースされる時点になっても、こうした作業予定のコメントがそのまま残っていることが少なくない。 このようなコメントが残っているのは、何らかの処理を組み込むべきなのに、すっかり忘れられてしまったことが原因であれば、重大な問題である。逆に言えば、作業予定のコメントが残っているのを見つけた顧客は、そのソフトウェアのプロジェクト管理に、重大な問題があるのではないか、という疑いを抱く。 実際には、仕様や設計が変更になって、コメントに書かれていたような作業が不要になった、というケースが多い。だが、作業が不要になった時点では、作業予定のコメントを書いた開発者がすでに担当を外れていることもある。そのため、作業予定のコメントをきちんと削除することは難しい。 プロジェクト管理に疑問を抱かせないためには、リリース前にコメントのレビューを行うか、もしくは、作業予定のコメントは記入しないように注意する必要がある。 ソフトウェア開発者としての責任感を疑われることは、技術力を低く評価されることよりも、深刻な問題である。ところが、いい加減な仕事をしているような印象を与えかねない致命的なコメントが、リリースされるソースコードに残っていることがある。例えば、次のようなものである。 ソースコードを書いている最中に、この通りで良いかどうか、疑問が生じることは良くある。いくつかの方法を試したり、設計を見直す必要があるかもしれない。時には、処理が正しいかどうかを、テストしないと確かめられないこともある。 本来であれば、そのような問題点は、開発者自身の作業項目リストに追加し、開発者自身が責任を持って検証やテストを行わなければならない。もし、検証やテストを行わずに、コメントを書いただけで終わりになっていたのであれば、本当に無責任だった、ということになる。 実際には、検証やテストを行った後で、コメントを修正するのを忘れているだけのことが多い。だが、こうした無責任なコメントは、顧客との信頼関係に重大な問題を引き起こす。開発者は、このようなコメントは最初からソースコードには書かないことが望ましい。 いかにオブジェクト指向に造詣が深く、デザインパターンを巧みに駆使したとしても、下手なコメントを書いてしまうと、せっかくの美しい設計が台無しになってしまう。 ソフトウェア開発者としての技術力を正しく評価してもらうためにも、コメントには最低限の注意は払うべきである。 |
セントラルファイナンスのサイトです。
