[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Proposal to change naming format to allow package-prefix/function-name

From: Zachary Kanfer
Subject: Proposal to change naming format to allow package-prefix/function-name
Date: Mon, 30 Dec 2019 02:02:42 -0500

I'd like to propose a change to the recommended symbol name format. Currently, Emacs recommends that public functions, macros, variables, etc, are named package-prefix-thing-name (https://www.gnu.org/software/emacs/manual/html_node/elisp/Coding-Conventions.html).

> 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 space1. Use two hyphens to separate prefix and name if the symbol is not meant to be used by other packages.

This works, but I find not as readable as could be. When looking at any function with three or more words in its name, it's not obvious where the package name stops, and the function name begins. For example, is the function lsp-java-organize-imports part of the lsp package, and called "java-organize-imports", or part of the lsp-java package, and called "organize-imports"? Is there a package named lsp-java-organize? You don't know from the function name.


I'd like to suggest allowing the use of a slash character to separate the package prefix from the rest of the function name. So, our example of lsp-java-organize-imports would become lsp-java/organize-imports. Then, it's obvious the package prefix is lsp-java.

This extends well to private funtions too, by repeating the slash character. For example, cl--do-arglist could become cl//do-arglist. This actually is a slight visual pun -- two slashes is a comment in C, Java, _javascript_, etc, and private functions are similarly intended to be somewhat hidden from the user.

I don't wish to disallow the dash from separating the package prefix from the rest of the name, only allow an alternative that I believe to be more readable.

==Prior Art & Existing Uses==

Here are some examples that show this should be easily grokked:
1. Elsewhere in technology, a slash is used to indicate hierarchy -- Unix/Linux filesystems use the slash between a parent directory and the directory or file inside it, as do URLs.
2. Clojure separates the namespace name from the function name with a slash, as in clojure.core/refer.
3. Dates are often written with the slash separating the componenets of the date, as in 12/27/2019.

Some Elisp functions that are part of Emacs already follow this format.
1. Many eshell functions already follow this format, for example eshell/ls, eshell/exit, and eshell/define.
2. Pcomplete functions use this format, even some for more than one hierarchical level, e.g. pcomplete/gzip, pcomplete/erc-mode/complete-command, pcomplete/org-mode/block-option/src.
3. Org-plot has half a dozen functions, like org-plot/goto-nearest-table.

Some popular libaries have functions with this format:
1. Powerline, like pl/memoize and pl/default-mode-line.
2. Multiple-cursors uses this format for one hundred public functions.

This change, at least until we see how it is accepted, is only intended to be a change to the coding conventions for new code. I don't expect to go through and rename existing Emacs functions; I rather would like this to be a way to write Emacs packages that doesn't go against the Emacs coding conventions. I've searched the mailing list for related discussions, and haven't found much, so if there has been some, please point it out to me. I'm very interested in the reception here; I think this would improve readability of names.


Zachary Kanfer

reply via email to

[Prev in Thread] Current Thread [Next in Thread]