GNU Emacs 32.0.50 (9008bf64c3) のマニュアルを PLaMo 翻訳で機械翻訳したものです。誤訳を含むことがあります。原文: https://www.gnu.org/software/emacs/manual/html_node/elisp/Comment-Tips.html ・ emacs-doc.conao3.com

D.8 コメントの書き方のコツ

コメントについては、以下の規約を推奨します。

‘;’

セミコロン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マイナーモードによって見出しとして扱われるべきコメントに使用します。デフォルトでは、少なくとも3つのセミコロン(その後に単一のスペースと非空白文字が続く)で始まるコメントはセクション見出しとみなされ、2つ以下のセミコロンで始まるコメントは見出しとはみなされません。

(従来、関数内の行をコメントアウトする際にもトリプルセミコロンによるコメントが用いられてきましたが、この用法は推奨されず、セミコロン2つのみを使用することが推奨されます。これは関数全体をコメントアウトする場合にも同様であり、その際は同様にセミコロン2つを使用してください。)

最上位セクションにはセミコロンが3つ、サブセクションには4つ、サブサブセクションには5つというように使用されます。

通常、ライブラリには少なくとも4つのトップレベルセクションがあります。例えば、これらすべてのセクションの本文が非表示になっている場合:

;;; backquote.el --- implement the ` Lisp construct...
;;; Commentary:...
;;; Code:...
;;; backquote.el ends here

(ある意味で、最後の行はセクション見出しではありません。その後にテキストが続いてはならないからです。何しろ、ファイルの終端を示すものですから。)

ライブラリが長くなる場合は、コードを複数のセクションに分割することをお勧めします。これは、「Code:」セクションを複数のサブセクションに分割することで実現できます。長らくこれが唯一の推奨手法でしたが、代わりに複数のトップレベルコードセクションを採用する人も多くなっています。どちらのスタイルを選んでも構いません。

複数のトップレベルコードセクションを使用すると、新たなネストレベルを導入せずに済むという利点がありますが、一方で「Code」という名前のセクションにすべてのコードが含まれないことになり、使い勝手が悪くなります。これを避けるには、そのセクション内にコードを一切記述しないようにしてください。そうすることで、そのセクションはセクション見出しではなく、区切り線として扱うことができます。

最後に、見出しの末尾にコロンやその他の句読点を使用しないことをお勧めします。歴史的な経緯から、「Code:」および「Commentary:」の見出しはコロンで終わっていますが、他の見出しについても同様の表記は避けることをお勧めします。

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