意図としてのコメントはこう書く - うっくつさん本を読む。

コードコメントに書くべきは「意図」 - プログラマーの脳みそ、ソースコードの心脳問題 - プログラマーの脳みその話。

初心者のコードでも、意図が書かれているならレビューは容易に行える。意図不明のコードほど手に負えないものはない。

「コメントとして意図を書け」という論旨には全面同意なので、意図としてのコメントはこう書く、という手法の一例を書いてみる。

目的

その関数/変数は何をするものなのかを書く。

/**
 * 最大公約数を求める。
 */

仕様上の制限

静的型付き言語なら型自体が入力仕様の役割を持つ。しかし、一般の用語をそのまま実装するのは機能過剰だと思われる場合、仕様上で制限を加えるのが望ましい*1。

/**
 * 最大公約数を求める。
 *
 * 数学上の定義では任意個の数値に対して最大公約数を定義できるが、
 * 本関数は二つの数値に対してのみ適用できる。
 * また高速化のため、ソート済みの引数を渡す必要がある。
 *
 * @param m 正の整数
 * @param n m以上の整数
 *
 * @return mとnの最大公約数
 */

実装上の制限

仕様上は許されるが、現在の実装では制限されていることについて書く。バージョンアップに伴って変更される可能性があることまで明記しておくとさらに良い。

/**
 * 最大公約数を求める。
 *
 * 数学上の定義では任意個の数値に対して最大公約数を定義できるが、
 * 本関数は二つの数値に対してのみ適用できる。
 * また高速化のため、ソート済みの引数を渡す必要がある。
 *
 * @param m 正の符号付き32ビット整数
 * @param n m以上の符号付き32ビット整数
 *
 * @return mとnの最大公約数、符号付き32ビット整数
 */

assertionとして表記

曖昧な自然言語よりも明確なassertionで表記する。機械可読な表現であれば自動的に検証することも可能になる。

/**
 * 最大公約数を求める。
 *
 * 数学上の定義では任意個の数値に対して最大公約数を定義できるが、
 * 本関数は二つの数値に対してのみ適用できる。
 * また高速化のため、ソート済みの引数を渡す必要がある。
 *
 * @param m 正の符号付き32ビット整数
 * @param n m以上の符号付き32ビット整数
 *
 * @return mとnの最大公約数、符号付き32ビット整数
 *
 * @precond m instanceof int
 * @precond n instanceof int
 * @precond 0 <= m
 * @precond m <= n
 * @precond n <= Integer.MAX_VALUE
 * @postcond $retval instanceof int
 * @postcond 0 <= $retval
 * @postcond $retval <= m
 * @postcond m % $retval == 0
 * @postcond n % $retval == 0
 */

〆

これは要するに設計情報だ。まともな設計なら意図を充分に表現できる。意図を充分に表現できないものはまともな設計ではない(対偶)。
以前書いたpythonライブラリのDocAssertも参考に。
http://kilrey.com/python/library/decorators.html

*1:「また高速化のため、ソート済みの引数を渡す必要がある。」というのは仕様としてあまり良いものではないのだけど。