技術者の評価を下げる「悪い」コメントに注意しよう

自明

見れば分かることは、わざわざコメントとして書く必要はない。だが、自明なコメントは、実際のソースコードでは良く見かけるものだ。例えば、次のようなものである。

// ポインタに値をセットする。
m_pDoc = pDoc;
        

// DoModalを呼び出す。
int nRet = dlg.DoModal();
        

特に、プログラミングの初心者が書いたソースコードには、自明なコメントが大量に書かれていることがある。

自明なコメントは、無駄ではあるが、特に害をもたらすものではない。だが、あまりにも多いと、初心者が書いていると思われ、顧客を不安にすることがありそうだ。

日本語訳

日本人の書いたソースコードには、ソースコードをそのまま日本語に訳しただけのコメントが書かれていることが非常に多い。例えば、次のようなものである。

int x_value_min = 0;    // ｘ値の最小値
int x_value_max = 0;    // ｘ値の最大値
        

// ユーザを作成する。
pUser = CreateUser(user_name);
        

ソフトウェアの技術力と英語力は無関係だが、日本語訳のコメントが多く見られるのは、たいてい経験の浅い開発者のソースコードである。

日本語訳のコメントも、特に害をもたらすものではないが、あまりにも多いと、初心者が書いていると思われ、顧客を不安にすることがありそうだ。

記入漏れ

ソフトウェアの受託開発では、ファイルや関数のヘッダを、定型フォーマットで記述することが多い。だが、実装が終わったリリース前のソースコードを見ると、ヘッダに書くべき内容がきちんと記入されていることは稀である。

/* 
 * 関数名：PlotData
 * 内容　：(x,y)データをグラフにプロットする。
 * 引数　：
 * 返値　：
 */
int CGraph::PlotData( CDC* pDC, int nSize, const XY* xy ) {
        

記入漏れは、ソースコードのリリースの前にレビューを行えば防ぐことができる。逆に言えば、ヘッダに記入漏れがあると、きちんとレビューをしていない、と思われてしまうことになる。

不適切な名前の補足

ソースコードの可読性を高めるために、クラスや関数、変数の名前は分かりやすいものにすることが重要である。しかし、稀に暗号のような名前を付けるプログラマーがいる。

不適切な名前のままでは本人も読めなくなるためか、暗号のような名前の意味をコメントで補っていることがある。例えば、次のようなものである。

// 座標の配列。
POINT* ap = new POINT[n];

// 座標の配列を単方向連結リストに変換。
l1 = ap2l_1(ap, n);

// 座標の配列を双方向連結リストに変換。
l2 = ap2l_2(ap, n);
        

このような事例は、設計を行わずにやみくもにコーディングを行った場合に多く見られる。逆に、設計を重視するオブジェクト指向プログラミングでは、設計フェーズできちんとした名前が付けられるため、このような問題は発生しない。

ソースコードに、不適切な名前を補足するコメントが書かれていると、ソフトウェアの設計を行う技量がないと思われてしまうことになる。

嘘

ソースコードの誤りはコンパイルエラーやテストで検出できるが、コメントの誤りは気づかれにくい。そのため、たいていのソースコードには、誤った内容が書かれた嘘のコメントが少なからず存在する。

意識してコメントに嘘を書く開発者はいない。それでも嘘のコメントができてしまうのには、いくつか理由がある。

嘘のコメントがあると、読み手はソースコードとコメントのどちらが正しいのか分からないことがある。コメントの方が正しいように見える場合は、ソースコードが誤っていると判断され、ソフトウェアの品質にも疑問を持たれることになる。

作業予定

開発期間の長い大規模システムでは、実装に着手した時点でも、ソフトウェアの一部については、仕様がまだ未確定だったり、将来的に変更される予定になっていることがある。特に、最近主流となりつつある反復型の開発手法では、このようなケースも珍しくなくなった。

未確定な部分を実装する際、将来的に変更されることを、ソースコードにコメントとして書いておく開発者が意外に多い。例えば、次のようなものである。

// この部分は後で変更される予定。
        

// ここは暫定。将来的には削除される。
        

ところが、最終的にリリースされる時点になっても、こうした作業予定のコメントがそのまま残っていることが少なくない。

このようなコメントが残っているのは、何らかの処理を組み込むべきなのに、すっかり忘れられてしまったことが原因であれば、重大な問題である。逆に言えば、作業予定のコメントが残っているのを見つけた顧客は、そのソフトウェアのプロジェクト管理に、重大な問題があるのではないか、という疑いを抱く。

実際には、仕様や設計が変更になって、コメントに書かれていたような作業が不要になった、というケースが多い。だが、作業が不要になった時点では、作業予定のコメントを書いた開発者がすでに担当を外れていることもある。そのため、作業予定のコメントをきちんと削除することは難しい。

プロジェクト管理に疑問を抱かせないためには、リリース前にコメントのレビューを行うか、もしくは、作業予定のコメントは記入しないように注意する必要がある。

無責任

ソフトウェア開発者としての責任感を疑われることは、技術力を低く評価されることよりも、深刻な問題である。ところが、いい加減な仕事をしているような印象を与えかねない致命的なコメントが、リリースされるソースコードに残っていることがある。例えば、次のようなものである。

// ちゃんとテストしていないが、とりあえずこれでOKとする。
        

// ここで呼び出してはいけないかもしれない。
        

// ここは、排他制御をしなくても大丈夫か？
        

// この処理は正しくないかもしれない。要テスト。
        

// この関数を呼べばたぶん大丈夫。
        

ソースコードを書いている最中に、この通りで良いかどうか、疑問が生じることは良くある。いくつかの方法を試したり、設計を見直す必要があるかもしれない。時には、処理が正しいかどうかを、テストしないと確かめられないこともある。

本来であれば、そのような問題点は、開発者自身の作業項目リストに追加し、開発者自身が責任を持って検証やテストを行わなければならない。もし、検証やテストを行わずに、コメントを書いただけで終わりになっていたのであれば、本当に無責任だった、ということになる。

実際には、検証やテストを行った後で、コメントを修正するのを忘れているだけのことが多い。だが、こうした無責任なコメントは、顧客との信頼関係に重大な問題を引き起こす。開発者は、このようなコメントは最初からソースコードには書かないことが望ましい。