6

When programming in Emacs Lisp, should variable and function names always be lower case? According to The Emacs Lisp Style Guide they should use "lisp-case", but what is that? In Emacs Lisp manual the case of symbols is not mentioned.

The motivation for this question came when I studied the Lisp code for M-x buffer-menu, see https://github.com/emacs-mirror/emacs/blob/master/lisp/buff-menu.el

We see that the code mixes two types of symbols. One type is starting with Buffer-menu (note capital B) and the other is starting with buffer-menu.. I think this is confusing, is this a recommended way of programming?

Drew
  • 75,699
  • 9
  • 109
  • 225
Håkon Hægland
  • 3,608
  • 1
  • 20
  • 51
  • That is most certainly legacy code, like most of the things present in Emacs. – wasamasa May 03 '15 at 15:51
  • This might have something to do with the way the label appears in the GUI menu. I think that Info-related functions look like that too, but I'm not 100% sure. – wvxvw May 03 '15 at 16:07
  • Yes, Buffer menu, Info, and Customize are 3 of the most heavily used areas where some such distinction is made. – Drew May 03 '15 at 16:12

2 Answers2

13
  1. There is no GNU Emacs convention wrt case for Emacs-Lisp function and variable names. (There can be any number of such "conventions" that anyone could come up with, of course.)

  2. The "Emacs Lisp Style Guide" that you reference is just one person's proposed guidelines.

  3. A (very) few longstanding libraries distributed with Emacs do use two styles that you mentioned: Some names are title-case (capitalized) and some are lowercase.

    In some cases a distinction was made between names of commands and customizable variables that it is expected might be typed by users (e.g., for M-x or C-h f), and names of non-interactive functions and variables that are expected to be invoked mainly by keys or from Lisp code.

    But this has not been adopted generally, and it has not always been implemented consistently. It typically applies to particular modes (e.g. Info-mode) where there are lots of commands that a user is not expected to input by name.

    For example, the commands in buff-menu.el that are expected to be invoked mainly by M-x are lowercase (for typing convenience), and the commands that are bound to keys in the buffer-list display are capitalized, as are other objects in the library (variables, non-interactive functions, etc.).

    Such libraries are a small minority (hence the doc says that usually function and variable names are lowercase). But the logic behind this design by RMS 30 years ago is still valid today. The idea is to simplify choices (and typing) for commands that you might invoke using M-x, by excluding commands that are useful only in a particular buffer and are bound to keys there. So Info-prev-reference (bound to C-M-i in Info), but info-apropos (useful outside Info).

  4. Usually it makes sense to use all lowercase, especially for names that a user will type (e.g., to M-x, as input). It's just easier that way. And in practice most names are in fact lowercase.

But you can use whatever you want. Use whatever you feel is most convenient for your use cases. It is the particular context that should guide you.

If it is important for your use case to distinguish command Abc from command abc, go for it. This is Lisp. You can have command, variable, face,.. whatever names that start with digits, symbols (e.g. >), etc. - pretty much any chars you like.

If you want to keep things simple for most users who might type a name using a common keyboard, then you might want to stick with lowercase a to z plus digits and hyphen (-) instead of underscore (_), to obviate their needing to use the Shift key. But it's really up to you.

Drew
  • 75,699
  • 9
  • 109
  • 225
  • 3
    I am not sure I agree that one should `"use whatever style you want`".. I think an "official" standard like https://github.com/bbatsov/emacs-lisp-style-guide would be required in open source projects to avoid confusion. And then in the long run it would be great if everyone could adapt to that style. But of course, it is hardly realistic to hope for :) – Håkon Hægland May 03 '15 at 16:18
  • (1) "*it would be great if everyone could adapt to that style*". Why? What confusion? What's the problem? Anyway, if you think you've found a problem, and you have a solution/suggestion to propose for it, then please consider using `M-x report-emacs-bug` or posting to `emacs-devel@gnu.org`. (2) If there is a de facto standard, it is to use only lowercase, for simplicity and to avoid the kind of confusion that I'm guessing you're thinking of. But if not, just what confusion do you experience or envision if lowercase is used generally (which it is, 99% of the time)? – Drew May 03 '15 at 16:30
  • 4
    "Use whatever you want" is not a very good answer to a question about naming conventions. Especially in this case, where title-casing is almost never used. – Dmitry May 03 '15 at 17:42
  • 2
    Saying that *"There is no convention wrt case for Emacs-Lisp"* is almost completely wrong. There is no *enforced* convention, and maybe there was no convention at all 3 decades ago, but there is very much a *followed convention* nowadays. 95% of the defined symbols in Emacs are strictly lowercase, and the only libraries I could find that use upper-case date back to 1985. The developer is not obligated to do anything, but if the OP is asking for conventions then he ought to be told that there is one even if it is not mandatory. – Malabarba May 06 '15 at 08:55
  • @Malabarba: I referred to a *de facto* standard, and I said that it is "*used generally (which it is, 99% of the time)*". What are you adding, by saying that it is used 95% of the time? The question is "**should** *variable and function names* **always** *be lower case?*" There is no answer to "*should...always*", beyond what is most appropriate for your use case. I made clear that "*Generally, it makes sense to use all lowercase*" - so much for your "*he ought to be told*". There is no documented convention. There is a de facto standard. And what counts is one's use case. This is **Lisp**. – Drew May 06 '15 at 13:35
  • As I mentioned in a comment to another (deleted) answer: Vanilla (`emacs -Q`) *Emacs tells me there are* **14975** *symbols whose first letter is uppercase.* – Drew May 06 '15 at 13:38
  • 1
    @Drew Well, maybe we'll have to agree to disagree. To me, the answer to the "*should...always*" question is "*Yes you should, although you're not forced*". I can see that's more or less what you say on item 4, but you start by saying "there's no convention" and finish by saying "do whatever you want" which (I feel) buries item 4 to the reader. As for that 14875, that is the total number of defined symbols in vanilla `emacs -q`, which tells me you forgot to set `case-fold-search` to `nil`. ;-) The actual number of symbols with uppercase is **861** for me. – Malabarba May 06 '15 at 14:20
  • @Malabarba: (1) If you take pieces of my answer out of context then you can paint it anyway you like. (2) Yes, I forgot `case-fold-search` - I get 704. (3) The disagreement is (at least) over *you should*. What's important is **why** 99% of names are lowercase with hyphens: because (a) they *can* be (in particular, hyphen is allowed) and (b) they are easier to type (no shifting). **That's all.** It's not about fitting some mold. There is **no** *you should (but it's not enforced)*. There is only *it will be easier for users if you use lowercase, because they will not need to use Shift*. – Drew May 06 '15 at 14:33
  • 1
    (1) I'm not talking about specific pieces, I'm referring to the overall tone of the answer. When you read everything, the lesson in item 4 (which is the most important IMO) gets buried by the other stuff. Your new edit makes it better (enough for me to remove my downvote), but I still think it should say first and foremost *"if don't have strong opinions, just use hyphens and lowercase"* and then elaborate on the details. – Malabarba May 06 '15 at 14:52
5

Nothing is set in stone or enforced. That said, I highly recommend the lower-case and hyphens style.

The only relevant thing I've found is in custom.texi:

As described in @ref{Commands}, each Emacs command is a Lisp function whose definition provides for interactive use. Like every Lisp function, a command has a function name, which usually consists of lower-case letters and hyphens.

Apparently, there are ~6% of upcase symbols loaded on my system:

(let ((case-fold-search nil)
      (up 0)
      (down 0))
  (mapatoms (lambda (x)
              (cond ((string-match "^[A-Z]" (symbol-name x))
                     (cl-incf up))
                    ((string-match "^[a-z]" (symbol-name x))
                     (cl-incf down)))))
  (list up down (/ (float up) (+ up down))))
;; =>
;; (4518 67496 0.06273780098314216)
abo-abo
  • 13,943
  • 1
  • 29
  • 43
  • Here's one more possibly relevant thing, the following snippet will give you the percentage of symbols with uppercase. `(let ((case-fold-search nil)) (cl-loop for s being the symbols collect s into all if (string-match (rx upper) (symbol-name s)) collect s into upper finally return (* 100 (/ (length upper) 1.0 (length all)))))` – Malabarba May 06 '15 at 09:16
  • Note that the doc quoted is *descriptive*, not *prescriptive*. And certainly not *proscriptive*. It does not tell you what you *should* do; it tells you what you will find is usually the case, in practice. – Drew May 07 '15 at 15:07