22

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.

Community
  • 1
Tianxiang Xiong
  • 3,848
  • 16
  • 27
  • Look through the Emacs sources (`grep -r '^;;;; ' lisp`) for inspiration. – sds Mar 17 '16 at 19:38
  • @sds that turns up a few non-standard applications of ;;;; in the canonical sources ;) – Tyler Mar 17 '16 at 20:39
  • That's what I meant - this 4 semicolon recommendation cannot be taken too seriously, OTOH, one should also look at the file timestamp - these non-standard things could be obsolete. – sds Mar 17 '16 at 20:42

1 Answers1

16

Actually, 3-and-more semi-colons stand for headings, where the more semi-colons you put the deeper the nesting of the heading. So it should look like

;;; Main heading
;;;; Sub heading
;;;;; Sub sub heading
;;;; Another sub heading
;;; Next main heading
Stefan
  • 26,154
  • 3
  • 46
  • 84
  • That seems to be the common practice, but differs from the conventions listed in the Elisp manual linked in the question. Is that a bug in the manual? – Tyler Mar 18 '16 at 16:17
  • 4
    It's not just a question of practice. That's how `emacs-lisp-mode` configures `outline-minor-mode`. I suggest you report this as a documentation bug (I think the doc is unclear more than wrong, but the end result is the same). – Stefan Mar 18 '16 at 16:27
  • I have sent a bug report, and offered a suggestion to change the documentation to something else. I see that I can get the TexInfo source for the manual; is there a repository that I can clone and make a pull request against? – Tianxiang Xiong Mar 19 '16 at 03:49
  • @TianxiangXiong: Of course, the doc is part of Emacs's source code, so you can clone `git://git.sv.gnu.org/emacs.git` and then send a patch via `M-x report-emacs-bug`. – Stefan Aug 02 '17 at 13:11
  • For reference, [here are the Common Lisp conventions](http://www.lispworks.com/documentation/lw51/CLHS/Body/02_ddbe.htm). If Emacs Lisp really uses 3 semicolons for a heading but then 4 semicolons for a less prominent heading, that seems illogical and contrary to what I've seen in CL and other lisps. Maybe it's simply a better fit for org-mode style headings so they went with it for elisp too. – Lassi Nov 29 '18 at 14:41
  • @Lassi: Actually, Elisp's convention is very close to the one you reference. The only difference is that top-level comments should also use `;;` rather than `;;;` (they'll still be indented to column 0 since they're at toplevel), and this frees up `;;;` for use as a heading, so it can be seen as an optimization of CLHS's convention which removes one `;` from headings (CLHS convention doesn't mention what happens with `;;;;;` but it would make sense to treat it as a subheading). – Stefan Nov 29 '18 at 15:22
  • @Stefan The idea of the CL/traditional lisp convention is that more semicolons = more prominent. ELisp is almost like that too, but `;;;` and `;;;;` are swapped from that standpoint :) – Lassi Nov 29 '18 at 15:39
  • Does every heading should start with capital letter? If so maybe we should add it to "Emacs Lisp Reference Manual" – slk500 May 05 '23 at 18:12