Double hyphen in Elisp function names

Question

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)))))

Answer 1

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:

• Function naming with forward slash?
• Naming convention for variable and function names
• SO: Emacs lisp namespace and internal function conventions
• SO: What does internal mean in function names in Emacs Lisp?
• SO: What does the double minus (--) convention in function names mean in Emacs Lisp