Konventionen für Emacs-Lisp-Kommentare

17

Im Anhang D.7 des Emacs Lisp-Referenzhandbuchs werden einige Kommentartipps aufgeführt:

  • Einzelne Semikolons ( ;) sollten für Inline-Kommentare verwendet werden.
  • Doppelte Semikolons ( ;;) sollten für Zeilenkommentare verwendet werden.
  • Dreifache Semikolons ( ;;;) sollten für "Kommentare, die im Nebenmodus" Gliederung "als Überschrift angesehen werden sollten" verwendet werden.
  • Vierfache Semikolons ( ;;;;) sollten für Überschriften von Hauptabschnitten eines Programms verwendet werden.

Die Anwendungsfälle für einfache und doppelte Semikolons sind klar, aber es scheint keine scharfe Abgrenzung zwischen dreifachen und vierfachen Semikolons zu geben.

Insbesondere verwendet die Standarddokumentation für Emacs-Pakete, die von bereitgestellt wird, auto-insertdreifache Semikolons, niemals vierfache Semikolons, selbst für die Überschriften der höchsten Ebene wie Dateiname und Hauptabschnitte. Siehe folgendes Beispiel:

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

Was sind die Best Practices für Dreifach- und Vierfach-Semikolons?

Aktualisieren

Dank Stefans Antwort habe ich einen Fehlerbericht eingereicht und folgenden Vorschlag gemacht:

Ich schlage vor, die Beschreibung für drei Semikolons zu ändern:

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.

Ein Link zum "Nebenmodus" im Emacs-Handbuch wäre nützlich: https://www.gnu.org/software/emacs/manual/html_node/emacs/Outline-Mode.html

Der Abschnitt für vier Semikolons kann entfernt werden.

Tianxiang Xiong
quelle
Durchsuchen Sie die Emacs-Quellen ( grep -r '^;;;; ' lisp) nach Inspiration.
SDS
@sds, das einige nicht standardmäßige Anwendungen von ;;;; in den kanonischen Quellen;)
Tyler
Das habe ich gemeint - diese 4-Semikolon-Empfehlung kann man nicht allzu ernst nehmen, OTOH, man sollte sich auch den Datei-Zeitstempel ansehen - diese nicht standardmäßigen Dinge könnten obsolet sein.
SDS

Antworten:

13

Tatsächlich stehen 3 und mehr Semikolons für Überschriften, wobei die Verschachtelung der Überschrift umso tiefer ist, je mehr Semikolons Sie setzen. So sollte es aussehen

;;; Main heading
;;;; Sub heading
;;;;; Sub sub heading
;;;; Another sub heading
;;; Next main heading
Stefan
quelle
Dies scheint die gängige Praxis zu sein, unterscheidet sich jedoch von den Konventionen, die im Elisp-Handbuch aufgeführt sind, das in der Frage verlinkt ist. Ist das ein Fehler im Handbuch?
Tyler
3
Es ist nicht nur eine Frage der Übung. So wird emacs-lisp-modekonfiguriert outline-minor-mode. Ich schlage vor, Sie melden dies als Dokumentationsfehler (ich denke, das Dokument ist mehr als falsch, aber das Endergebnis ist das gleiche).
Stefan
Ich habe einen Fehlerbericht gesendet und einen Vorschlag gemacht, die Dokumentation zu ändern. Ich sehe, dass ich die TexInfo-Quelle für das Handbuch bekommen kann. Gibt es ein Repository, für das ich eine Pull-Anfrage klonen und stellen kann?
Tianxiang Xiong
@TianxiangXiong: Natürlich ist das Dokument Teil des Emacs-Quellcodes, sodass Sie git://git.sv.gnu.org/emacs.giteinen Patch klonen und dann über senden können M-x report-emacs-bug.
Stefan
Als Referenz dienen hier die Common-Lisp-Konventionen . Wenn Emacs Lisp wirklich 3 Semikolons für eine Überschrift verwendet, aber dann 4 Semikolons für eine weniger markante Überschrift, scheint dies unlogisch und im Gegensatz zu dem, was ich in CL und anderen Lisps gesehen habe. Vielleicht passt es einfach besser zu Überschriften im Org-Modus, also haben sie sich auch für elisp entschieden.
Lassi