[ニッキ] コメントは自分のための覚書じゃない

少なくとも、業務で、チームの一員として書いたコードでは。

業務で、チームの一員として書いたコードのコメントってのは、メンバーのために書くものだと思う。

デバッグのための役に立つ情報かもしれないし、あまり知られていないアルゴリズムを解説するものかもしれない。

「いいコメント」の例は Python の DocString だろう。Python の標準モジュールの DocString は自分のためではなく、Python を使う開発者 ( つまりユーザ ) のために書かれている。そのメソッドの引数は何か、何をするのか、戻り値として何を返すのかといった自分以外の開発者にとって有益なことが書かれている。

少なくとも、


int hoge = 32; // 数値に意味はない


なんてのはコメントのうちに入らない ( 数値に意味がないならなんで代入してるんだ？ ) し、


// XXX
void functionname( args ){
....( 以下略 )


なんてのは論外だ ( XXX って何だよ？これみて何を理解しろってんだ？ )

個人で趣味で書いたコードならどう書いてもいいと思うけどね。

わたしは Python の DocString のようなコメントを心がけて行こう。

2007.11.14 追記

なんか誤解されていたので追記。

XXX って書いてあること自体は悪いことじゃない。

悪いのは XXX だけ しか書いていないことだ。

# XXX ( 確かめなきゃいけないこととか )

↑みたいに「何をしなければならないのか」とか「なにが不確かなのか」といったメッセージが書かれているのならばそれでいいと思う。