15

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.

  • 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
13

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
  • 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
  • 3
    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 3: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 2 '17 at 13:11
  • For reference, here are the Common Lisp conventions. 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

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.