Next: Emacsライブラリーのヘッダーの慣習, Previous: ドキュメント文字列のヒント, Up: ヒントと規約 [Contents][Index]
コメントにたいして以下の慣習を推奨します:
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つ以下のセミコロンで始まるものはみなさない。
(歴史的に3連セミコロンのコメントは関数内の行のコメントアウトに使用されたきたが、この用途では2つだけのセミコロン使用を推奨し、3連セミコロンの使用は推奨しない。これは2連セミコロンを使用して関数全体をコメントアウトする際にも適用される。)
セミコロン3つはトップレベルのセクション、4つはサブセクション、5つはサブサブセクション、のように使用される。
ライブラリーは通常はトップレベルのセクションを少なくとも4つもつ。たとえばこれらのセクションすべてが隠されているときは:
;;; backquote.el --- implement the ` Lisp construct... ;;; Commentary:... ;;; Code:... ;;; backquote.el ends here
(テキストが後続することがあってはならない最後の行は、ある意味セクションヘッダーではない。これは最終的にはファイル終端をマークする。)
長いライブラリーではコードを複数セクションに分割するのが賢明である。これは‘Code:’セクションを複数のサブセクションに分割することで行うことができる。長い間、これが推奨される唯一のアプローチであったとはいえ、多くの人が複数のトップレベルセクションの使用を選択してきた。あなたはいずれかのスタイルを選択できる。
トップレベルのコードセクションの複数使用には、ネスティングレベルの追加導入を避けるという利点があるが、それはすべてのコードが‘Code’という名前のセクションに含まれていないという不体裁な結果をも意味する。これを避けるためには、そのセクション内部にコードを何も配置しないこと。この方法により、それをセクションヘッダーではなくセパレーターとみなすことができる。
この問題に対象するためにヘッダーをコロンや他の句読点で終了させないことを最後に推奨しておく。歴史的な理由により‘Code:’と‘Commentary:’のヘッダーはコロンで終わるが、何にせよ他のヘッダーに同じことを行わないことをお勧めする。
一般的に言うとコマンドM-;
(comment-dwim)は適切なタイプのコメントを自動的に開始するか、セミコロンの数に応じて既存のコメントを正しい位置にインデントします。Manipulating Comments in The GNU Emacs Manualを参照してください。