2

Why do some people use -- in their function names? Here's an example from elfeed-search.el:

(defun elfeed-search--header ()
  "Returns the string to be used as the Elfeed header."
  (if (eql (car elfeed-search--header-cache) (buffer-modified-tick))
      (cdr elfeed-search--header-cache)
    (let* ((header (elfeed-search--header-1))
           (cache (cons (buffer-modified-tick) header)))
      (prog1 header
        (setf elfeed-search--header-cache cache)))))
  • 1
    Related question; seems to indicate a symbol is internal to a package. – Juancho Jun 27 '18 at 20:35
  • 5
    See the second bullet point in (elisp) Coding Conventions, as well as (elisp) Tips for Defining. – Basil Jun 27 '18 at 20:36
  • 1
    @Basil Please write an answer and cite the relevant part of the link you gave. The OP should accept that answer afterwards. – Tobias Jun 28 '18 at 0:29
  • 1
    @Tobias Done, please review. – Basil Jun 28 '18 at 10:50
5

Why do some people use -- in their function names?

This is a standard Elisp convention for indicating the function is internal, i.e. one that should not be used or depended on by external packages. Quoth (elisp) Coding Conventions:

You should choose a short word to distinguish your program from
other Lisp programs.  The names of all global symbols in your
program, that is the names of variables, constants, and functions,
should begin with that chosen prefix.  Separate the prefix from the
rest of the name with a hyphen, ‘-’.  This practice helps avoid
name conflicts, since all global variables in Emacs Lisp share the
same name space, and all functions share another name space(1).
Use two hyphens to separate prefix and name if the symbol is not
meant to be used by other packages.

The same convention exists for other definitions, such as variables and constants. Quoth (elisp) Tips for Defining:

‘PREFIX--...’
     The variable is intended for internal use and is defined in the
     file ‘PREFIX.el’.  (Emacs code contributed before 2018 may follow
     other conventions, which are being phased out.)

Note that your sample function is found in the file elfeed-search.el, so it is using the symbol elfeed-search as the package prefix for all its definitions. This convention is also widespread and mentioned in (elisp) Packaging Basics:

   Each package (whether simple or multi-file) has certain “attributes”:

Name
     A short word (e.g., ‘auctex’).  This is usually also the symbol
     prefix used in the program (see Coding Conventions).

Note also that some older packages, notably the built-in man.el and info.el, additionally follow the weaker convention of starting certain definitions with a capital letter, e.g. the user option Man-filter-list, the idea being that said definitions do not "get in the way" of case-sensitive completion. This convention is no longer followed IME. See the following thread for discussion of this: https://lists.gnu.org/archive/html/emacs-devel/2017-11/msg00452.html


Some related SE/SO posts:

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.