外部仕様としてのコメント
関数の説明をコメントで書く時に、気をつけることは、全ての引数の意味を書くこと。そうやって研究室の人には言っているのだが、一応ココにも書いておく。
私がお奨めする方法は、全ての引数が登場する文で関数を説明すること。例えば、
void DrawEpiline(Image *img, Mat F, Point p);
の説明として、
// 基礎行列 F に関して一方の画像上の点 p に対応するエピポーラ線 // l = Fp // を他方の画像 img に引く
と書いてあれば、(エピポーラ線はこの関数をつかう人なら知っているとして)明確だろう。
なぜか次のように書きたがる人が多いが、私としてはとても読みづらいし、行数も多くなる。
// エピポーラ線を引く // [入力] // img: エピポーラ線が引かれる画像 // F: 基礎行列 // p: 画像上の点の座標 // [出力] // 返り値: なし // img: エピポーラ線が引かれた画像
いや、こんな風に書く人はいないか?まぁ、それはいいや。大事なのは、説明中に引数名を全て登場させることであって、そのような文がかけないような関数は、設計が失敗しているのではないかと考えられる。それは明らかに複雑怪奇すぎるか、自分でも理解してないかのいずれかだろう。
あとはポインタ引数に const と (C99 なら restrictも)を適切につければ、入力やら出力やらとわざわざ言葉で説明する必要もなくなる。