| Top Of Page | 目的と効果 | コメントの手間 | コメントの単位 | そしてコメントよりも | Bottom |
そして、意識しなければならないことがあります。
「コーディング(ソースコードを書く事をしばしばこう表現します)における、ドキュメンテーションの主役はコメントではない」ということです。
では主役はなにか？
それは、適切なプログラム構造、シンプルなデータ構造、直接的で判りやすい実現手法、よい変数名、よいルーチン名、明瞭なレイアウトなど─つまり、これまで触れてきた事が、主役なのです。
コメントを、粗末に書く事は簡単ですが、完璧に書く事は非常に難しく、下手なコメントはソースコードを読む際の助けにならず、害になることもしばしばあります。
また、コードの説明を行うコメントは、もちろん正当なものですが、できればコメントによる説明がなくても判りやすい、自明なコードであることが望ましいのです。
コードのまとめ、そしてコードの意図の記述は、コメントとして価値が高いものです。
多すぎるコメントは、少なすぎるのと同じように、好ましくありません。ほどほどの量を心がけましょう。
より問題が大きいのは、下の理由です。
「コメントを書く」という時間は、実は「プログラムの理解を深める」時間でもあるのです。
また、コメントはコードと同時に書きましょう。
コメンテーションの主役は、「パラグラフのコメント」です。良く考えてコメントしましょう。
パラグラフのコメントとしてのガイドラインは、
制御構造のコメントとは、たとえばループが始まる前に、これは何のループかをコメントしておくものです。もちろん if などの時に、どういう if なのかのコメントもこれに含まれます。
ルーチンのコメントに関しては、以下のようなガイドラインが一般的ですし、また効果的です。
そして、モジュールのコメントです。
しかしコメントが不要なわけではもちろんありません。
効果的に使えば、非常に強力な助けになります。
自信を持って、しかし慎重にコメントすべきです。
役立つコメントを書いているかということを検証するために、他の人(先輩など)に、自分のプログラムを説明してみるといいでしょう。
「ここはなぜこうしたの？」「これは何をしているの？」と質問する、その答えがコメントに書いてあれば最高です。
そこまででなくても、その質問のヒントとなるようなコメントは、コメントする価値があったということです。
何度目かになりますが、コードは読ませるものなのです。
コメントの目的と効果
一般に、コメントを目的別に分類すると、以下のようになります。
この中で、コードの反復は、意味がありません。ただの自己満足です。
たまにあるんですよ、
a = b; /* bをaにコピーする */
こんなコメントが。(^^; そんなことコメントしてもらわなくてもわかるわい(笑)
これが、コードの反復のコメントです。
コードの修正をしている途中で目印を埋め込む事もありますが、修正が終わったらそういったコメントは消した方がきれいです。残っていると、後で他の人が調べた時に混乱する元となります。
なぜこの方法を選んだのか、その判断が正しいのだということを、コメントで記述しましょう。
そして、コメントするときは、実装レベルのコメントではなく、仕様レベルのコメントを心がけましょう。
同じものに対してコメントする時、たとえば、/* 従業員情報を取得 */と/* EmpRec構造体に設定 */では、前者のほうがよいです。
コメントの手間
コメントが重要なのは判っているけど、時間が…スケジュールが…
うんうん、よくわかります。もう骨身にしみてわかります。私も、そうですから。
しかし…自戒を込めて、あえていえば「ええいだまらっしゃい！」((c)ご隠居)です(^^;
コメントに時間がかかるのは、次の２つの理由によることが多いでしょう。
このうち、上の理由は、工夫次第でなんとでもなります。
たとえば、
/************************************************************************
* Copyright (c) xxxxxxxx Co.,Ltd. *
* *
* QMCALLBK.C -- Functions / Queue Manager Window Message callback *
* procedures *
* *
* Written: 1995.12.20 Takao Tamura / Technology Research Division *
* Update : 1997.08.11 Takao Tamura / Technology Laboratory *
* BUG FIX: I avoided by the direct communication with a *
* : device driver to the phenomenon that the dispatch*
* : from message cue becomes imperfect from a *
* : specific model. *
* Update : 1999.10.01 Takao Tamura / Technology Center *
* MODIFY : Interchangeability was lost as a result of the *
* : version rise of a driver. *
************************************************************************/
/************************************************************************
Copyright (c) xxxxxxxx Co.,Ltd.
QMCALLBK.C -- Functions / Queue Manager Window Message callback
procedures
Written: 1995.12.20 Takao Tamura / Technology Research Division
Update : 1997.08.11 Takao Tamura / Technology Laboratory
Reason :(Bug Fix)
I avoided by the direct communication with a device driver to the
phenomenon that the dispatch from message cue becomes imperfect from
a specific model.
Update : 1999.10.01 Takao Tamura / Technology Center
Reason :(Modified)
Interchangeability was lost as a result of the version rise of a driver.
*************************************************************************/
この二つのコメントスタイルの場合なら、下のほうが楽です。上の例は、上は、いちいち「*」とか「:」とかをそろえなくてはなりません。
その程度…と感じるかもしれませんが、ソース本数が多くなるとそうもいきません。
このように、修正が苦痛にならないコメント様式を予め検討すべきです。(かっこいいかどうかだけで決めるべきではありません。)
「プログラムが何をしているのか、ちょうどよい言葉が見つからない」
不穏です。こういう理由でコメントできない場合は、プログラムが何をしているか理解していない証拠であることが多いのです。
そして「プログラムの理解を深める」ことは、コメントを書くかどうかに関わらず、プログラマには必要な時間といえます。
せっかくその時間をつかって考えを深めたなら、コメントしておきませんか？
後付けのコメントは、検索が多くなり、作業量が増え、そして正確さに欠けます。
「コードを組むことに集中しているのに、それをコメント書きで中断したくない」という意見もあります。なるほどそういう考え方もありますが──しかし考えてみてください。
そんなに集中が必要なコードは、予め、何をするのか日本語で(頭の中で)まとめておくべきですよね。
そして、頭の中でまとめるなら、それをコメントにしない手はありません(^^)V 。
コメントの単位
さきほどは、コメントの目的で分けましたが、こんどはコメントの単位でわけます。
コメントの単位で分けた場合、以下の単位でのコメントが考えられます。
上の方が範囲が小さく、下の方が範囲が大きいです。
よいコードであれは、それぞれの行でコメントをする必要は殆どありません。行にコメントが必要な理由は、「その行がすごく複雑で説明がいる」「かつてエラーがあり、それを記録しておきたい」の２つです。頻繁な行末コメントは、インデントや修正の際に邪魔になるだけですので、避けましょう。
例外もあります。「データ宣言時」と「ブロックの終了」です。 この時は、行末コメントが活きてきます。
たとえば、
int Boundary; /* ソート済み配列の上位インデックス */
int InsertVal; /* ソート済み配列への入力値 */
int InsertPos; /* ソート済み配列の入力値を入れる際の位置 */
これがデータ宣言の行末コメントですし、
while (s16Low < s16High) {
s16Mid = (s16Low + s16High) / (S_16)2;
if (IsamKeyComp(&lpIdxPage->item[s16Mid].keys,
lpKey, u32KeyType) <= 0) {
s16Low = s16Mid + (S_16)1;
}
else {
s16High = s16Mid;
}
}/* end while
この、/* end while */ がブロックの終了です。
さて、そのパラグラフのコメントですが…、例を挙げますと以下のようなものです。
パラグラフのコメント
/* ルートの交換 */
OldRoot = root1;
root1 = root2;
root2 = OldRoot;
これを行末コメントでやってしまうと、
OldRoot = root1; /* root1をOldRootに保存する */
root1 = root2; /* root2をroot1に代入する*/
root2 = OldRoot; /* OldRootをroot2に代入する */
こんな風になっちゃいます。一行一行コメントするようなとこじゃありませんよね。
これを意識してコメントすると、ソースコードを読むときに助けになる、コメントしがいのあるコメントが書けると思います。
できるだけ、仕様領域の言葉を心がけましょう。たとえば、
/* アロケーションフラグが０の場合 */
if (fAlloc == 0) {
........
}
これと
/* 新しいメンバをアロケーションする場合 */
if (fAlloc == 0) {
........
}
これでは、下のほうがいいわけです。
特に企業でプログラミングしている場合、ルーチンとモジュールのコメントは、企業から指定されていることも多いと思います。それらにはきちんと理由がありますので、よほどのことがないかぎり従うべきでしょう。
そして、コメントよりも
上手にドキュメントされたコードのコメントは多くの場合、パラグラフに対して数行のコメントで、その意図を示しています。
繰り返しになりますが、なるべく、HOWではなく、WHAT、WHYのコメントを心掛けましょう。HOWのコメントはなくても、コードから自明であるべきです。
つまり、「何をしているのか」「何故そうしているのか」が判るコメントです。「どのようにそれをしているのか」というのは、説明するまでもなく判るというシンプルなコードが望ましいのです。
HOWのコメントが必要なロジックは、かなりトリッキー(曲芸的)なものか、ハードに依存しなければならないようなときに出現します。もちろん、望ましくありません。
１９７８年に、カーニハン＆ブラウガが言った名台詞は、現在のプログラミングでもそのまま当てはまります。
「トリッキーなコードにコメントするな、書き直せ！」
プログラムにちょっと慣れてくると、トリッキーなコードが書ける自分が誇らしく、そういうコードを書きたくなる時があります。
ふっ、こんなに複雑なコードを組んでしまったぜ！俺ってスゴイ！…うんうん、わかりますその気持ち。なんて初々しい(笑)
＃私もそんな時期がありましたとも。(笑)
＃もはやそんな「可愛い」頃は事象の地平面の彼方ですが(笑)
でも、必ず、トリッキーでない方法が見つかるはずです。トリッキーであることを喜んではいけません。スマートな手段を探しましょう。
あんなに複雑に思えたこの処理、こんなにシンプルじゃないか！なんてすばらしい！
そう思える人こそが、真の達人なのです。
おまけ
グラフィカルなコメント。話の種に(笑)
ちょっと邪道ですが、こんなコメントもあります。
参考までに。
| はじめに | ルーチン | モジュール | 変数名の力 | 変数使用法 | 制御構造 | レイアウト | コメント | テスト | デバッグ | 謝辞 | Top of Site |