DOSEIの日記

技術メモ+日常ログ

外部仕様としてのコメント

関数の説明をコメントで書く時に、気をつけることは、全ての引数の意味を書くこと。そうやって研究室の人には言っているのだが、一応ココにも書いておく。

私がお奨めする方法は、全ての引数が登場する文で関数を説明すること。例えば、

void DrawEpiline(Image *img, Mat F, Point p);

の説明として、

// 基礎行列 F に関して一方の画像上の点 p に対応するエピポーラ線
// l = Fp
// を他方の画像 img に引く

と書いてあれば、(エピポーラ線はこの関数をつかう人なら知っているとして)明確だろう。
なぜか次のように書きたがる人が多いが、私としてはとても読みづらいし、行数も多くなる。

// エピポーラ線を引く
// [入力]
//   img: エピポーラ線が引かれる画像
//   F:   基礎行列
//   p:   画像上の点の座標
// [出力]
//   返り値: なし
//   img: エピポーラ線が引かれた画像

いや、こんな風に書く人はいないか?まぁ、それはいいや。大事なのは、説明中に引数名を全て登場させることであって、そのような文がかけないような関数は、設計が失敗しているのではないかと考えられる。それは明らかに複雑怪奇すぎるか、自分でも理解してないかのいずれかだろう。

あとはポインタ引数に const と (C99 なら restrictも)を適切につければ、入力やら出力やらとわざわざ言葉で説明する必要もなくなる。