Konventionen für Emacs-Lisp-Kommentare

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.

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