A.4 コメントの書き方のヒント

コメントを置く場所とそれらの字下げ方法については以下のような慣習を推奨します。

`;'

1つのセミコロン`;'で始まるコメントは、 ソースコードの右側で同じコラム位置に揃えること。 そのようなコメントは、その行のコードの動作を説明する。 lispモードやその関連するモードでは、 コマンドM-;（indent-for-comment）で 自動的に右側の正しい位置に`;'を挿入したり、 そのようなコメントが既存ならば整列できる。

つぎとその下の例は、Emacsのソースから持ってきたものである。

          (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つのセミコロンで始まるコメントを関数のまえに書くこと。 各引数の意味とその可能な値を関数がどのように解釈するかを正確に説明すること。

`;;;'

3つのセミコロン`;;;'で始まるコメントは、左端に揃えること。 そのようなコメントは、関数定義の外側で使い、 プログラムの設計原理を説明する一般的な表明である。 たとえばつぎのとおり。

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

3つのセミコロンで始まるコメントの別の使い方は、 関数内の行をコメントにする場合である。 そのような行が左端に留まるように3つのセミコロンを使うのである。

          (defun foo (a)
          ;;; This is no longer necessary.
          ;;;  (force-mode-line-update)
            (message "Finished with %s" a))
     

`;;;;'

4つのセミコロン`;;;;'で始まるコメントは、 左端に揃えて、プログラムの主要な部分のヘッダに使う。 たとえばつぎのとおり。

          ;;;; The kill ring
     

M-;（indent-for-comment）や <TAB>（lisp-indent-line）などの Emacsのlispモードの字下げコマンドは、 これらの慣習にしたがって自動的にコメントを字下げします。 See コメントの操作。