From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED.blaine.gmane.org!not-for-mail From: Zachary Kanfer Newsgroups: gmane.emacs.devel Subject: Proposal to change naming format to allow package-prefix/function-name Date: Mon, 30 Dec 2019 02:02:42 -0500 Message-ID: Mime-Version: 1.0 Content-Type: multipart/alternative; boundary="000000000000a90350059ae66e6d" Injection-Info: blaine.gmane.org; posting-host="blaine.gmane.org:195.159.176.226"; logging-data="111229"; mail-complaints-to="usenet@blaine.gmane.org" To: emacs-devel@gnu.org Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Mon Dec 30 08:03:03 2019 Return-path: Envelope-to: ged-emacs-devel@m.gmane.org Original-Received: from lists.gnu.org ([209.51.188.17]) by blaine.gmane.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.89) (envelope-from ) id 1ilp4x-000Soy-MZ for ged-emacs-devel@m.gmane.org; Mon, 30 Dec 2019 08:03:03 +0100 Original-Received: from localhost ([::1]:58960 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1ilp4w-0001jR-Ev for ged-emacs-devel@m.gmane.org; Mon, 30 Dec 2019 02:03:02 -0500 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:51749) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1ilp4q-0001jK-Pk for emacs-devel@gnu.org; Mon, 30 Dec 2019 02:02:58 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1ilp4p-0007CO-49 for emacs-devel@gnu.org; Mon, 30 Dec 2019 02:02:56 -0500 Original-Received: from mail-yb1-xb43.google.com ([2607:f8b0:4864:20::b43]:43100) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1ilp4o-0007C1-Ti for emacs-devel@gnu.org; Mon, 30 Dec 2019 02:02:55 -0500 Original-Received: by mail-yb1-xb43.google.com with SMTP id v24so13771051ybd.10 for ; Sun, 29 Dec 2019 23:02:54 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=mime-version:from:date:message-id:subject:to; bh=rQQfS2wNCRujUi4To70rzDrfUwDV5IgtiK6+6wOkpyA=; b=MwnHrMiu379OjuhUnPC9Ac6jeJqZnqaRrLElqWOe6sdsSYB9d5lcmHhyIPULncwYAg oU0YaNlf4ysUqE4R31Jkulb63ceCMYKTXyfe1kZbpAkrupQud71vyVI3/N5glpd2GBLr RpxYzicjCLqR0z0Q6cMX44ZhCJlWN2CBnZAt9gkFHtQaDdhm1Bwh60sGW4SSNn+5h/7l fLOrT493lV3PA9iNjAtLPxM8F6TNmnL69Hk0Jvd7dEIg0OjgGWIumjzEXG+7A+38IKjZ 0Ui3dXJ6WexiwYLIl3B6UtRIiXwEN7Aamwy3YFj4+WYqetSvIQe4y/rDKonujrk30LRI 9JHw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:mime-version:from:date:message-id:subject:to; bh=rQQfS2wNCRujUi4To70rzDrfUwDV5IgtiK6+6wOkpyA=; b=r24d/8l8I1crKDaZ6N2adVT8SOfAwOHsBAJlsM1Winow+P98lrl6weFSb7gGaS8KNS nbtTRe6a9Bvo5mz0VKeVcpurp9DBILmujbhraXJlMnlB04hgbTsUmMRpcNI4P4bdBU3t xAGljtWNRD4Yq6FIX9RJtRKZSGq4OznqRRMT2EHpgSXNDqn3zGsbmoekHbkwFKJJxks5 Ab2t8RlehXOTVzAez9PZvIfTG4SVD9xJi0EhY4ZK/OJMtZQcZ/5cL/df0WNwrwVNExWZ ndkXvDjZUs3Igw2H/JOTXp0QX+vLG5srhjisWsBKZiEStJ9bpzFO+Lb1no9SpqDmRwLA YTxg== X-Gm-Message-State: APjAAAXUEeO3C7x/stISbMC1QiuHXdsOneULD15wt42+7+R9uNLxfYaH TXOAdjbgfGH0n9uM3YDKasif4rrPZnD7u0NBfmSwvVDh/iM= X-Google-Smtp-Source: APXvYqwSelKTrY37tC92GFsaA/i9ILlNVXyQa7MevT/bYTCDPZOwp8fTVNh8/AzpAYhBpi1U0QJzDYGQ3pypbRQoCDg= X-Received: by 2002:a25:e08f:: with SMTP id x137mr48901849ybg.497.1577689373277; Sun, 29 Dec 2019 23:02:53 -0800 (PST) X-detected-operating-system: by eggs.gnu.org: Genre and OS details not recognized. X-Received-From: 2607:f8b0:4864:20::b43 X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Original-Sender: "Emacs-devel" Xref: news.gmane.org gmane.emacs.devel:243758 Archived-At: --000000000000a90350059ae66e6d Content-Type: text/plain; charset="UTF-8" Content-Transfer-Encoding: quoted-printable 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-Convention= s.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, =E2=80= =98-=E2=80=99. 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. =3D=3DProposal=3D=3D 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. =3D=3DPrior Art & Existing Uses=3D=3D 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. Thanks, Zachary Kanfer --000000000000a90350059ae66e6d Content-Type: text/html; charset="UTF-8" Content-Transfer-Encoding: quoted-printable
I'd like to propose a change to the recommended symbol= name format. Currently, Emacs recommends that public functions, macros, va= riables, etc, are named package-prefix-thing-name (https= ://www.gnu.org/software/emacs/manual/html_node/elisp/Coding-Conventions.htm= l).

> You should choose a short word to distinguish your prog= ram from other Lisp programs. The names of all global symbols in your progr= am, 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, =E2=80=98-=E2=80=99. This practice helps avoid name conflicts, s= ince 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 packa= ge name stops, and the function name begins. For example, is the function l= sp-java-organize-imports part of the lsp package, and called "java-org= anize-imports", or part of the lsp-java package, and called "orga= nize-imports"? Is there a package named lsp-java-organize? You don'= ;t know from the function name.

=3D=3DProposal=3D=3D

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

This extends well to private fun= tions too, by repeating the slash character. For example, cl--do-arglist co= uld become cl//do-arglist. This actually is a slight visual pun -- two slas= hes is a comment in C, Java, Javascript, etc, and private functions are sim= ilarly intended to be somewhat hidden from the user.

I don't wis= h 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.
=
=3D=3DPrior Art & Existing Uses=3D=3D

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 sla= sh separating the componenets of the date, as in 12/27/2019.

Some El= isp 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 s= ome for more than one hierarchical level, e.g. pcomplete/gzip, pcomplete/er= c-mode/complete-command, pcomplete/org-mode/block-option/src.
3. Org-plo= t 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 w= e see how it is accepted, is only intended to be a change to the coding con= ventions 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 packa= ges that doesn't go against the Emacs coding conventions. I've sear= ched 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 interest= ed in the reception here; I think this would improve readability of names.<= /div>

Thanks,

Zachary Kanfer
--000000000000a90350059ae66e6d--