About `<prefix>--' (was Re: filenotify.el)

[Stephen Berman <stephen.berman@gmx.net>]

On Wed, 26 Jun 2013 08:40:11 +0200 Michael Albinus <michael.albinus@gmx.de> wrote:

> Rüdiger Sonderfeld <ruediger@c-plusplus.de> writes:
>
>> One minor nitpick I forgot:  You should use two hyphens for functions which 
>> are not meant to be used by the user.
>
> Ahh. This is a rather new coding style in Emacs; it didn't even find
> its way into the Lisp Refefence Manual yet :-)

Actually, it did, but just barely, in (elisp)Coding Conventions:

     Separate the prefix from the rest of the name with a hyphen, `-'.
     Use two hyphens if the symbol is not meant to be used by other
     packages.  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

I have two problems with this.  First, the "Use two hyphens" sentence
shouldn't come between the other two, since "This practice" in the
following sentence only refers to using the prefix, not two hyphens.
Second, "not meant to be used by other packages" is too vague for me to
feel confident about how to apply it.  For example, in the new version
of todo-mode.el I recently committed to the trunk, there aren't really
any symbols, including those naming commands and user options, meant to
be used by other packages, since it's not a general purpose library.  On
the other hand, it does contain some internal functions and variables of
a rather general character, needed to implement parts of the UI, which I
included because Emacs doesn't have them (e.g. a powerset function), and
these certainly could be used by other packages, but more likely they
would be reimplemented using the package prefix.  So it's not clear to
me where the dividing line is.  It could be taken to be everything
except commands and user options, as Rüdiger seems to imply (unless he
meant "the user" is a package, not a human).  But it's clearly not been
used so restrictively in Emacs to date (indeed, mpc.el even contains a
command `mpc--faster').  So I would find it helpful if there were more
specific guidelines about how to apply this convention.

Steve Berman