The Emacs Lisp Reference Manual's Appendix D.7 mentions some comment tips:
- Single semicolons (
;
) should be used for inline comments. - Double semicolons (
;;
) should be used for line comments. - Triple semicolons (
;;;
) should be used for "comments which should be considered a heading by Outline minor mode". - Quadruple semicolons (
;;;;
) should be used for headings of major sections of a program.
The single and double semicolon use cases are clear, but there does not seem to be a sharp delineation between triple and quadruple semicolons.
In particular, the standard documentation for Emacs packages provided by auto-insert
uses triple semicolons, never quadruple semicolons, even for the highest-level headings like file name and major sections. See example below:
;;; 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
What are the best practices for triple and quadruple semicolons?
Update
Thanks to Stefan's answer, I have filed a bug report and made the following suggestion:
I suggest that the description for three semicolons be changed to:
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.
A link to "Outline minor mode" in the Emacs manual would be useful: https://www.gnu.org/software/emacs/manual/html_node/emacs/Outline-Mode.html
The section for four semicolons can be elided.
grep -r '^;;;; ' lisp
) for inspiration.