D.7 コメント記述のヒント

コメントにたいして以下の慣習を推奨します:

‘;’

1つのセミコロン‘;’で始まるコメントはソースコードの右側の同じ列にすべて揃えられる。そのようなコメントは通常はその行のコードがどのように処理を行うかを説明する。たとえば:

(setq base-version-list                 ; There was a base
      (assoc (substring fn 0 start-vn)  ; version to which
             file-version-assoc-list))  ; this looks like
                                        ; a subversion.

‘;;’

2つのセミコロン‘;;’で始まるコメントはコードと同じインデントレベルで揃えられる。そのようなコメントは通常はその後の行の目的や、その箇所でのプログラムの状態を説明する。たとえば:

(prog1 (setq auto-fill-function
             …
             …
  ;; Update mode line.
  (force-mode-line-update)))

わたしたちは通常は関数の外側のコメントにも2つのセミコロンを使用する。

;; This Lisp code is run in Emacs when it is to operate as
;; a server for other processes.

関数がドキュメント文字列をもたなければ、かわりにその関数の直前にその関数が何を行うかと、正しく呼び出す方法を説明する2つのセミコロンのコメントをもつこと。各引数の意味と引数で可能な値をその関数が解釈する方法を正確に説明すること。しかしそのようなコメントはドキュメント文字列に変換するほうがはるかに優れている。

‘;;;’

3つのセミコロン‘;;;’で始まるコメントは左マージンから始まる。わたしたちはOutlineマイナーモードのheading(ヘッダー)とみなされるべきコメントにそれらを使用している。デフォルトでは少なくとも(後に1つの空白文字と非空白文字が続く)3つのセミコロンはsectionとみなして、2つ以下のセミコロンで始まるものはsectionとみなさない。歴史的に3連セミコロンのコメントは関数内の行のコメントアウトにも使用されるが、この使用は推奨しない。

関数全体をコメントアウトするときは2つのセミコロンを使用する。

‘;;;;’

4つ(以上)のセミコロン‘;;;;’で始まるコメントは左マージンに揃えられ、プログラムのメジャーセクションのヘッダーに使用される。たとえば:

;;;; The kill ring

これらのheadingの下にsub-headingsをもちたければ、sub-headingsをネストするためにより多くのセミコロンを使用すること。

一般的に言うとコマンドM-; (comment-dwim)は適切なタイプのコメントを自動的に開始するか、セミコロンの数に応じて既存のコメントを正しい位置にインデントします。Manipulating Comments in The GNU Emacs Manualを参照してください。