Мы рекомендуем следующие соглашения для комментариев:
Комментарии, начинающиеся с одной точки с запятой ‘;’, должны быть выровнены по одному столбцу в правой части исходного кода. Такие комментарии обычно объясняют, как код в этой строке выполняет свою работу. Например:
(setq base-version-list ; Существовала базовая
(assoc (substring fn 0 start-vn) ; версия, к которой
file-version-assoc-list)) ; это, по-видимому,
; относится как подверсия.
Комментарии, начинающиеся с двух точек с запятой ‘;;’, должны быть выровнены по тому же уровню отступа, что и код. Такие комментарии обычно описывают назначение следующих строк или состояние программы в данной точке. Например:
(prog1 (setq auto-fill-function
…
…
;; Обновить строку режима.
(force-mode-line-update)))
Обычно мы также используем две точки с запятой для комментариев вне функций.
;; Этот Lisp-код выполняется в Emacs, когда он должен работать ;; как сервер для других процессов.
Если функция не имеет строки документации, то непосредственно перед ней должен быть комментарий с двумя точками с запятой, объясняющий, что делает функция и как её правильно вызывать. Следует точно объяснять, что означает каждый аргумент и как функция интерпретирует его возможные значения. Однако гораздо лучше преобразовывать такие комментарии в строки документации.
Комментарии, начинающиеся с трёх (или более) точек с запятой ‘;;;’, должны начинаться с левого поля. Мы используем их для комментариев, которые должны рассматриваться как заголовки в режиме свертки Outline minor mode. По умолчанию комментарии, начинающиеся как минимум с трёх точек с запятой (после которых следует один пробел и не пробельный символ), считаются заголовками разделов, а комментарии с двумя или меньшим количеством — нет.
(Исторически комментарии с тремя точками с запятой также использовались для закомментирования строк внутри функции, но такое использование не рекомендуется, вместо этого следует использовать две точки с запятой. Это также относится к закомментированию целых функций; в этом случае также используйте две точки с запятой.)
Три точки с запятой используются для разделов верхнего уровня, четыре — для подразделов, пять — для подподразделов и так далее.
Обычно библиотеки имеют как минимум четыре раздела верхнего уровня. Например, когда тела всех этих разделов скрыты:
;;; backquote.el --- реализация Lisp-конструкции `... ;;; Commentary:... ;;; Code:... ;;; backquote.el ends here
(В некотором смысле последняя строка не является заголовком раздела, так как после неё никогда не должно быть текста; в конце концов, она отмечает конец файла.)
Для более крупных библиотек желательно разбивать код на несколько разделов. Это можно сделать, разбив раздел ‘Code:’ на несколько подразделов. Хотя долгое время это был единственный рекомендуемый подход, многие предпочитают использовать несколько разделов верхнего уровня для кода. Вы можете выбрать любой стиль.
Использование нескольких разделов верхнего уровня для кода имеет то преимущество, что позволяет избежать введения дополнительного уровня вложенности, но также означает, что раздел с именем ‘Code’ не содержит весь код, что неудобно. Чтобы избежать этого, следует не помещать никакого кода внутрь этого раздела; тогда его можно рассматривать как разделитель, а не как заголовок раздела.
Наконец, мы рекомендуем не завершать заголовки двоеточием или каким-либо другим знаком препинания. По историческим причинам заголовки ‘Code:’ и ‘Commentary:’ заканчиваются двоеточием, но мы рекомендуем не делать так для других заголовков.
Вообще говоря, команда M-; (comment-dwim) автоматически начинает комментарий подходящего типа или выравнивает существующий комментарий в нужное место, в зависимости от количества точек с запятой. См. Управление комментариями в Руководстве по GNU Emacs.