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?
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.