Виды комментариев в Emacs Lisp

Виды комментариев в Emacs Lisp.

Содержание

1 Общая информация

  • Есть три типа комментариев:

    • ; комментарии в одной строке с кодом;
    • ;; комментарии, которые не находятся на одной строке с кодом;
    • ;;; Комментарий, используемый в качестве заголовков.
  • Пример использования всех типов комментариев:

    ;;; My heading
    ;; A function that greets people
    (defun greet (&optional name)
      "My function"
      (message
       (concat "Hello "
               (if name ; check if nil
                   name
                 "World"))))
    
    (greet)
    ;; This prints Hello World
    
    (greet "Gene")
    ;; This prints Hello Gene
    
  • Команда M-; (comment-dwim) автоматически создаёт комментарий соответствующего типа или смещает существующий комментарий в нужное место, в зависимости от количества точек с запятой.

  • Литература

2 Соглашения для комментариев

2.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.2 ;;

  • Комментарии, начинающиеся с двух точек с запятой ;;, должны быть выровнены по тому же уровню отступа, что и код.
  • Такие комментарии обычно описывают назначение следующих строк или состояние программы в этот момент:
    (prog1 (setq auto-fill-function
                 
                 
      ;; Update mode line.
      (force-mode-line-update)))
    
  • Также этот тип комментария используется для комментариев вне функций:
    ;; This Lisp code is run in Emacs when it is to operate as
    ;; a server for other processes.
    
  • Если у функции нет строки документации, вместо этого она должна иметь комментарий с двумя точками с запятой прямо перед функцией, объясняющий, что делает функция и как ее правильно вызывать.
  • Следует объяснить, что означает каждый аргумент и как функция интерпретирует его возможные значения.

2.3 ;;;

  • Комментарии, начинающиеся с трех (или более) точек с запятой ;;;, должен начинаться с левого края.
  • Используется для комментариев, которые должны считаться заголовком.
  • По умолчанию комментарии, начинающиеся как минимум с трех точек с запятой (за которыми следует один пробел и символ, не являющийся пробелом), считаются заголовками разделов, а комментарии, начинающиеся с двух или менее, — нет.
  • Три точки с запятой используются для разделов верхнего уровня, четыре для подразделов, пять для подразделов и так далее:
    ;;; backquote.el --- implement the ` Lisp construct...
    ;;; Commentary:...
    ;;; Code:...
    ;;; backquote.el ends here
    

Links to this note

Дмитрий Сергеевич Кулябов
Дмитрий Сергеевич Кулябов
Профессор кафедры теории вероятностей и кибербезопасности

Мои научные интересы включают физику, администрирование Unix и сетей.

Похожие