次: , 前: Formatting, 上: Writing C


5.2 あなたの仕事のコメント

どんなプログラムでもそれが何なのか簡単に表すコメントで始まるべきだ。例: `fmt - filter for simple filling of text'.

英語は全ての国のほとんど全てのプログラマが読むことのできる唯一の言語なの で、GNUプログラムでは英語でコメントを書いてほしい。もしあなたが英語を上 手く書けないなら、出来るだけ上手く英語でコメントを書き、他の人々にそれら を書き直すのを手伝ってくれるよう頼んでください。もし英語でコメントを書く ことができないなら、一緒に仕事してくれる誰かを探して、あなたのコメントを 英語に翻訳してもらってください。

それぞれの関数に、その関数が何をやり、どういう引数を受け取り、引数のあり 得る値が何を意味し、そして何に使われるのかを表すコメントを書いてください。 もしCの型が習慣的なやり型で使われるなら、Cの引数宣言の意味をくどくどと複 製する必要はない。もしその利用が(実際には文字列の最初ではなく、二文字目 のアドレスであるchar *型の引数のような)標準的でないものだったら、 あるいは、(改行を含む文字列は動作保証されない、というような)期待される方 法では働かない値があり得るなら、そう書くのを忘れないようにしなさい。

また、もしあるなら、返り値の意味を説明しなさい。

Emacsのセンテンス・コマンド(sentence command)が働くように、コメントの行 の最後の後に二つのスペースを置いてください。また、完全な文を書き、最初の 単語を大文字で書いてください。もし小文字の識別子が文の最初に来たら、それ を大文字で書いてはいけない! 綴りを変えると違う識別子になる。もし小文字で 文を始めるのが好きじゃないなら、文を違うように書きなさい(例えば、“The identifier lower-case is ...”)。

関数の上のコメントは、引数の値について言うときにその引数の名前を使えば、 ずっとはっきりする。変数名それ自体は小文字であるべきだが、変数そのもので はなく、その値について言っているときには大文字で書きなさい。従って、“an inode”よりも、“the inode number NODE_NUM”である。

普通コメントに関数の名前を再び言うことに意味はない。なぜなら、読者は自分で それを見ることができるからだ。関数自身がスクリーンの一番下からはみ出てし まうぐらいコメントが長いときは例外かもしれない。

静的な変数それぞれにも、次のようにコメントがあるべきだ。

     /* Nonzero means truncate lines in the display;
        zero means continue them.  */
     int truncate_lines;

すべての`#endif'に、入れ子になっていない(たった数行の)短い条件分岐 の場合を除いて、コメントを付けるべきだ。そのコメントには、 その意味を含めて、終了する条件分岐の状態を記すべきだ。 `#else'はその条件と続くコードの意味を記述するコメントを持つ べきだ。例えば、

     #ifdef foo
       ...
     #else /* not foo */
       ...
     #endif /* not foo */
     #ifdef foo
       ...
     #endif /* foo */

しかし、対照的に、`#ifndef'では次のようなコメントを書く。

     #ifndef foo
       ...
     #else /* foo */
       ...
     #endif /* foo */
     #ifndef foo
       ...
     #endif /* not foo */