Convenciones de comentarios de Emacs Lisp

17

El Apéndice D.7 del Manual de referencia de Emacs Lisp menciona algunos consejos de comentarios:

  • Los puntos y comas simples ( ;) deben usarse para comentarios en línea.
  • Se ;;deben utilizar puntos y comas dobles ( ) para comentarios de línea.
  • Los puntos y comas triples ( ;;;) se deben utilizar para "comentarios que se deben considerar un encabezado por el modo secundario Esquema".
  • Los puntos y comas cuádruples ( ;;;;) deben usarse para encabezados de secciones principales de un programa.

Los casos de uso de punto y coma de punto y coma simples son claros, pero no parece haber una delimitación clara entre punto y coma y punto y coma cuádruples.

En particular, la documentación estándar para los paquetes de Emacs proporcionada por auto-insertutiliza punto y coma triple, nunca punto y coma, incluso para los títulos de más alto nivel, como el nombre de archivo y las secciones principales. Ver ejemplo a continuación:

;;; test.el --- A test file.                         -*- lexical-binding: t; -*-

;; Copyright (C) 2016

;; Author:  John Smith
;; Keywords: 

;; This program is free software; you can redistribute it and/or modify
;; it under the terms of the GNU General Public License as published by
;; the Free Software Foundation, either version 3 of the License, or
;; (at your option) any later version.

;; This program is distributed in the hope that it will be useful,
;; but WITHOUT ANY WARRANTY; without even the implied warranty of
;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
;; GNU General Public License for more details.

;; You should have received a copy of the GNU General Public License
;; along with this program.  If not, see <http://www.gnu.org/licenses/>.

;;; Commentary:

;; 

;;; Code:



(provide 'test)
;;; test.el ends here

¿Cuáles son las mejores prácticas para los puntos y comas triples y cuádruples?

Actualizar

Gracias a la respuesta de Stefan , presenté un informe de error e hice la siguiente sugerencia:

Sugiero que la descripción de tres puntos y comas se cambie a:

Comments that start with three semicolons, ‘;;;’, are considered
top-level headings by Outline minor mode.

Four or more semicolons can be used as subheadings in hierarchical
fashion. E.g.

;;; Main heading
;;;; Sub heading
;;;;; Sub sub heading
;;;; Another sub heading
;;; Next main heading

These comments should be used to break Emacs Lisp code into sections.

Sería útil un enlace al "Modo secundario del esquema" en el manual de Emacs: https://www.gnu.org/software/emacs/manual/html_node/emacs/Outline-Mode.html

La sección para cuatro puntos y comas se puede elidir.

Tianxiang Xiong
fuente
Mire a través de las fuentes de Emacs ( grep -r '^;;;; ' lisp) en busca de inspiración.
sds
@sds que muestra algunas aplicaciones no estándar de ;;;; en las fuentes canónicas;)
Tyler
Eso es lo que quise decir: esta recomendación de 4 puntos y coma no se puede tomar demasiado en serio, OTOH, también se debe mirar la marca de tiempo del archivo: estas cosas no estándar podrían ser obsoletas.
sds

Respuestas:

13

En realidad, 3 y más puntos y comas representan encabezados, donde más puntos y comas colocas, más profundo es el anidamiento del encabezado. Entonces debería verse como

;;; Main heading
;;;; Sub heading
;;;;; Sub sub heading
;;;; Another sub heading
;;; Next main heading
Stefan
fuente
Esa parece ser la práctica común, pero difiere de las convenciones enumeradas en el manual de Elisp vinculadas en la pregunta. ¿Es eso un error en el manual?
Tyler
3
No es solo una cuestión de práctica. Así es como se emacs-lisp-modeconfigura outline-minor-mode. Le sugiero que informe esto como un error de documentación (creo que el documento no está claro más que mal, pero el resultado final es el mismo).
Stefan
Envié un informe de error y ofrecí una sugerencia para cambiar la documentación a otra cosa. Veo que puedo obtener la fuente de TexInfo para el manual; ¿Hay un repositorio en el que pueda clonar y realizar una solicitud de extracción?
Tianxiang Xiong
@TianxiangXiong: Por supuesto, el documento es parte del código fuente de Emacs, por lo que puede clonar git://git.sv.gnu.org/emacs.gity luego enviar un parche a través de M-x report-emacs-bug.
Stefan
Como referencia, aquí están las convenciones de Common Lisp . Si Emacs Lisp realmente usa 3 puntos y coma para un encabezado pero luego 4 puntos y coma para un encabezado menos prominente, eso parece ilógico y contrario a lo que he visto en CL y otros ceceos. Tal vez sea simplemente una mejor opción para los encabezados de estilo del modo org, por lo que también lo usaron para elisp.
Lassi