Document that symbol prefix "my-" (or other) should be left for users

Document that symbol prefix "my-" (or other) should be left for users

[Teemu Likonen]

[-- Attachment #1: Type: text/plain, Size: 1495 bytes --]

It seems to me that Emacs users often use "my-" prefix or person's
initials (like "tl-" or "tl/") as prefix when writing their private
extensions and configuration. However, there is no officially documented
prefix which Emacs promises to leave for users. So I suggest making such
promise and documenting it in info page "(elisp) Coding Conventions"
(example patch below).

What is suitable prefix? It should be short. "my-" and "user-" are
already used somewhere.


--8<---------------cut here---------------start------------->8---
commit 526387c4d62f06d932f7885cc4f047a0fa255381
Author: Teemu Likonen <tlikonen@iki.fi>
Date:   2015-12-13 19:58:57 +0200

    tips.texi: Document that symbol prefix `my-' is for users

diff --git a/doc/lispref/tips.texi b/doc/lispref/tips.texi
index ffce920..37186c6 100644
--- a/doc/lispref/tips.texi
+++ b/doc/lispref/tips.texi
@@ -89,6 +89,9 @@ Coding Conventions
 If one prefix is insufficient, your package can use two or three
 alternative common prefixes, so long as they make sense.
 
+Finally, prefix @code{my-} should be reserved for users, their private
+features and configuration. Don't use it in public packages.
+
 @item
 Put a call to @code{provide} at the end of each separate Lisp file.
 @xref{Named Features}.
--8<---------------cut here---------------end--------------->8---

-- 
/// Teemu Likonen   - .-..   <https://github.com/tlikonen> //
// PGP: 4E10 55DC 84E9 DFF6 13D7 8557 719D 69D3 2453 9450 ///

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 818 bytes --]

RE: Document that symbol prefix "my-" (or other) should be left for users

[Drew Adams]

> It seems to me that Emacs users often use "my-" prefix or person's
> initials (like "tl-" or "tl/") as prefix when writing their private
> extensions and configuration.

Yes.  As in any other language.

> However, there is no officially documented prefix which Emacs
> promises to leave for users.

Right.  As for any other language (?).

> So I suggest making such promise and documenting it in info
> page "(elisp) Coding Conventions"

Why?  What is the problem for which this would be a good solution?

Are you afraid that someone will create a function or variable
with prefix `my-', and that a user who uses that code will be
precluded from defining the same name, or that if s?he defines
another name that uses the same prefix s?he will be confused?

Did you encounter a real problem in this area?

Re: Document that symbol prefix "my-" (or other) should be left for users

[Teemu Likonen]

[-- Attachment #1: Type: text/plain, Size: 614 bytes --]

Drew Adams [2015-12-13 10:32:20-08] wrote:

>> So I suggest making such promise and documenting it in info
>> page "(elisp) Coding Conventions"
>
> Why?  What is the problem for which this would be a good solution?

> Did you encounter a real problem in this area?

I have had zero problems but it's also near-zero effort to decide a
prefix, document it and obey it. And yes, it's for avoiding name
conflicts: so that user's configuration won't harm future Emacs
functionality, nor the other way around.

But it's just a suggestion. I'm not going to have a month long
discussion about this. So just ignore it. :-)

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 818 bytes --]

Re: Document that symbol prefix "my-" (or other) should be left for users

[John Wiegley]

>>>>> Teemu Likonen <tlikonen@iki.fi> writes:

> I have had zero problems but it's also near-zero effort to decide a prefix,
> document it and obey it. And yes, it's for avoiding name conflicts: so that
> user's configuration won't harm future Emacs functionality, nor the other
> way around.

> But it's just a suggestion. I'm not going to have a month long
> discussion about this. So just ignore it. :-)

I appreciate the effort, Teemu, but I don't think it needs explicit
documentation. The only package that could conceivably use "my-" as a prefix
would have to be called "my", otherwise it's in violation of other Emacs
coding standards. At that point, a user who uses such a "my" package can
either choose not to (to preserve the "my-" namespace for themselves), or
request that the author change its name.

-- 
John Wiegley                  GPG fingerprint = 4710 CF98 AF9B 327B B80F
http://newartisans.com                          60E1 46C4 BD1A 7AC1 4BA2

Re: Document that symbol prefix "my-" (or other) should be left for users

[Tassilo Horn]

John Wiegley <jwiegley@gmail.com> writes:

>> I have had zero problems but it's also near-zero effort to decide a
>> prefix, document it and obey it. And yes, it's for avoiding name
>> conflicts: so that user's configuration won't harm future Emacs
>> functionality, nor the other way around.
>
>> But it's just a suggestion. I'm not going to have a month long
>> discussion about this. So just ignore it. :-)
>
> I appreciate the effort, Teemu, but I don't think it needs explicit
> documentation. The only package that could conceivably use "my-" as a
> prefix would have to be called "my", otherwise it's in violation of
> other Emacs coding standards.

There are some packages which have a long name and then use a short
abbreviation for (parts of) their functions and variables.  For example,
the `ace-window' package defines functions and variables with the
prefixes ace-* and aw-* (the latter mostly for "private" stuff).  At
least the aw-* symbols could easily clash with Anton Wiegley's private
stuff.

I just picked `ace-window' from the top of my head.  I'm pretty sure
there are more packages which use some abbreviation of their name as
prefix.

Despite clashes, such abbreviations make those packages also less
discoverable using the normal auto-completion features C-h f/v.

Bye,
Tassilo

Re: Document that symbol prefix "my-" (or other) should be left for users

[John Yates]

[-- Attachment #1: Type: text/plain, Size: 614 bytes --]

On Tue, Dec 15, 2015 at 1:22 PM, Tassilo Horn <tsdh@gnu.org> wrote:

> There are some packages which have a long name and then use a short
> abbreviation for (parts of) their functions and variables.  For example,
> the `ace-window' package defines functions and variables with the
> prefixes ace-* and aw-* (the latter mostly for "private" stuff).  At
> least the aw-* symbols could easily clash with Anton Wiegley's private
> stuff.
>

How about reserving '/' as the user prefix delimiter and '-' as the package
prefix delimiter?  Then Anton Wiegley's aw/foo will never conflict with
ace-window's aw-foo.

/john

[-- Attachment #2: Type: text/html, Size: 1098 bytes --]

RE: Document that symbol prefix "my-" (or other) should be left for users

[Drew Adams]

> How about reserving '/' as the user prefix delimiter and '-'
> as the package prefix delimiter?  Then Anton Wiegley's aw/foo
> will never conflict with ace-window's aw-foo.

Again, why?  Why reserve any prefix for users?  We haven't yet
yet seen a reason.  (This is quite different from key-binding
prefixes, IMO.)

Re: Document that symbol prefix "my-" (or other) should be left for users

[John Wiegley]

>>>>> Drew Adams <drew.adams@oracle.com> writes:

> Again, why? Why reserve any prefix for users? We haven't yet yet seen a
> reason. (This is quite different from key-binding prefixes, IMO.)

Drew has a point. How about we wait until there's some instance of the problem
in the wild that needs us to document such a convention? There's been a lot of
time for this to become an issue, and it hasn't yet.

Even then, it would only ever be a convention: we can't stop authors from
naming their symbols however they want -- except for those that are proposed
to Emacs or ELPA, where a "my-" prefix would already raise the necessary
eyebrows.

-- 
John Wiegley                  GPG fingerprint = 4710 CF98 AF9B 327B B80F
http://newartisans.com                          60E1 46C4 BD1A 7AC1 4BA2

Re: Document that symbol prefix "my-" (or other) should be left for users

[David Reitter]

On Dec 13, 2015, at 1:32 PM, Drew Adams <drew.adams@oracle.com> wrote:
> 
>> It seems to me that Emacs users often use "my-" prefix or person's
>> initials (like "tl-" or "tl/") as prefix when writing their private
>> extensions and configuration.
> 
> Yes.  As in any other language.

Which language would that be?

The vast majority of modern languages have some form of scoping that determines the namespace for global-like variables, often with several levels of hierarchy.

RE: Document that symbol prefix "my-" (or other) should be left for users

[Drew Adams]

> >> It seems to me that Emacs users often use "my-" prefix or person's
> >> initials (like "tl-" or "tl/") as prefix when writing their private
> >> extensions and configuration.
> >
> > Yes.  As in any other language.
> 
> Which language would that be?

Ok, you got me.

So can you give a reason why Emacs-Lisp coding conventions
should reserve such a prefix (or any other) for users?
Haven't heard any reason, so far.

Re: Document that symbol prefix "my-" (or other) should be left for users

[Chad Brown]

> On 15 Dec 2015, at 17:26, Drew Adams <drew.adams@oracle.com> wrote:
> 
> So can you give a reason why Emacs-Lisp coding conventions
> should reserve such a prefix (or any other) for users?
> Haven't heard any reason, so far.

I have seen people run into conflicts several times (over a long
time frame). At MIT, many students started out with simple
lisp functions added to a mostly-plain emacs. Eventually, they’d
add packages, and occasionally hit conflicts. A convention of
user/function-name would have avoided all of those.

This was in the time before package.el became widespread, so I
believe that packages are added to emacs far more often now than
they were then. Of course, back then, MIT’s intro CS class was
based on Scheme, so probably there are fewer people writing
personal lisp into nearly-empty .emacs files these days.

So: if you want to know if it has ever happened: absolutely. I don’t
know if this sort of thing comes up much anymore; MIT students’
experience doesn’t involve emacs nearly as much these days as it did
back then.

Hope that helps,
~Chad

RE: Document that symbol prefix "my-" (or other) should be left for users

[Drew Adams]

> > So can you give a reason why Emacs-Lisp coding conventions
> > should reserve such a prefix (or any other) for users?
> > Haven't heard any reason, so far.
> 
> I have seen people run into conflicts several times (over a
> long time frame)...  So: if you want to know if it has ever
> happened: absolutely.

The question I raised is not whether users have run into name
conflicts but why Emacs coding conventions should reserve any
given name prefix (or prefixes?) for users.

Users can run into name conflicts also if they use the same
"reserved" prefix `my-' (or `my/' or `my31459265358979535/'
or whatever).

Re: Document that symbol prefix "my-" (or other) should be left for users

[Evans Winner]

John Wiegley <jwiegley@gmail.com> writes:

     Drew has a point. How about we wait until there's some
     instance of the problem in the wild that needs us to
     document such a convention? There's been a lot of time
     for this to become an issue, and it hasn't yet.

For what it's worth, it's happened to me, but a long time
ago and I don't remember what function name I stepped on.
If it's happened to me, I would guess it's happened to other
people.  Creating a name clash isn't a bug in Emacs, so why
would I (or anyone else) report it?  So if it's happening,
it might not be something that would come up on the radar
here very often.  I finally discovered what I'd done and
jsut renamed my function.

Short of giving Elisp a package system like Common Lisp, it
seems that the solution is just to make sure your personal
prefix is complex enough that it is unlikely to be
duplicated in other people's code.

Re: Document that symbol prefix "my-" (or other) should be left for users

[Chad Brown]

> On 15 Dec 2015, at 17:52, Drew Adams <drew.adams@oracle.com> wrote:
> 
>>> So can you give a reason why Emacs-Lisp coding conventions
>>> should reserve such a prefix (or any other) for users?
>>> Haven't heard any reason, so far.
>> 
>> I have seen people run into conflicts several times (over a
>> long time frame)...  So: if you want to know if it has ever
>> happened: absolutely.
> 
> The question I raised is not whether users have run into name
> conflicts but why Emacs coding conventions should reserve any
> given name prefix (or prefixes?) for users.
> 
> Users can run into name conflicts also if they use the same
> "reserved" prefix `my-' (or `my/' or `my31459265358979535/'
> or whatever).

Specifically, I’ve seen users run into name conflicts with things
like ABC-function where ABC was both a shortened package reference
and a user’s initials. Many packages use AB- or ABC- as a package
prefix. Many users use AB/ or ABC/ as a user-specific prefix. I’ve never
seen those swapped (personally).

~Chad

Re: Document that symbol prefix "my-" (or other) should be left for users

[John Wiegley]

>>>>> Evans Winner <ego111@gmail.com> writes:

> For what it's worth, it's happened to me, but a long time ago and I don't
> remember what function name I stepped on. If it's happened to me, I would
> guess it's happened to other people. Creating a name clash isn't a bug in
> Emacs, so why would I (or anyone else) report it? So if it's happening, it
> might not be something that would come up on the radar here very often. I
> finally discovered what I'd done and jsut renamed my function.

Good point, Evans. Perhaps it occurs more often than we realize.

I'm not sure a convention will result in it never happening again, in the same
way that key mapping conventions have not stopped various packages from
stomping on bindings that were reserved to me as a user.

Perhaps we could recommend that users consider their init file to be a sort of
package, and thus use a `.emacs-' prefix for their symbols, as they might when
writing any other package.

-- 
John Wiegley                  GPG fingerprint = 4710 CF98 AF9B 327B B80F
http://newartisans.com                          60E1 46C4 BD1A 7AC1 4BA2

Document that symbol prefix "my-" (or other) should be left for users

[Teemu Likonen]

[-- Attachment #1: Type: text/plain, Size: 501 bytes --]

* 2022-07-10 08:57:16-0400, Stefan Monnier wrote:

> Maybe we should officially declare the `my-` prefix as reserved for the
> end-user.

I support that and proposed it already in 2015-12-13:
<https://lists.gnu.org/archive/html/emacs-devel/2015-12/msg00556.html>.

There is an example documentation patch in the message but some people
opposed the idea and nothing happened.

-- 
/// Teemu Likonen - .-.. https://www.iki.fi/tlikonen/
// OpenPGP: 6965F03973F0D4CA22B9410F0F2CAE0E07608462

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 251 bytes --]

Re: Document that symbol prefix "my-" (or other) should be left for users

[Stefan Kangas]

Teemu Likonen <tlikonen@iki.fi> writes:

> I support that and proposed it already in 2015-12-13:
> <https://lists.gnu.org/archive/html/emacs-devel/2015-12/msg00556.html>.
>
> There is an example documentation patch in the message but some people
> opposed the idea and nothing happened.

I tend to agree with John Wiegley here, when he says that it doesn't
really need explicit documentation:

    https://lists.gnu.org/r/emacs-devel/2015-12/msg00608.html

It just seems to be more words added to the ELisp manual for little
benefit.

Re: Document that symbol prefix "my-" (or other) should be left for users

[Bozhidar Batsov]

[-- Attachment #1: Type: text/plain, Size: 755 bytes --]

Agreed. Not to mention this prefix is not super common - a ton of people user their name, initials, etc. E.g. `boz-my-command`. 

On Sun, Jul 10, 2022, at 7:59 PM, Stefan Kangas wrote:
> Teemu Likonen <tlikonen@iki.fi> writes:
> 
> > I support that and proposed it already in 2015-12-13:
> > <https://lists.gnu.org/archive/html/emacs-devel/2015-12/msg00556.html>.
> >
> > There is an example documentation patch in the message but some people
> > opposed the idea and nothing happened.
> 
> I tend to agree with John Wiegley here, when he says that it doesn't
> really need explicit documentation:
> 
>     https://lists.gnu.org/r/emacs-devel/2015-12/msg00608.html
> 
> It just seems to be more words added to the ELisp manual for little
> benefit.
> 
> 

[-- Attachment #2: Type: text/html, Size: 1445 bytes --]

Re: Document that symbol prefix "my-" (or other) should be left for users

[Tim Cross]

"Bozhidar Batsov" <bozhidar@batsov.dev> writes:

> Agreed. Not to mention this prefix is not super common - a ton of people user their name, initials, etc. E.g. `boz-my-command`. 
>

Yep, I have used my-command and often tx-command  (for my initials x =
cross and yes, not great due to tx/rx being often used for send/receive,
though never been an issue so far).

The other 'convention' I see is my/command or my~command. I do find my/
or tx/ appealing, although I haven't 'switched' to use it.

One possible 'nice' advantage of my- would be that if it was flagged as
a 'personal' or reserved prefix, borrowing customisations and
bits of code from others would potentially be easier to add (but I guess
perhaps that is not necessarily a good thing!).

I'd love to have real namespace support in elisp. Something like Cl
packages or even better, something like Clojure where you can require a
package and specify either a prefix alias used to access symbols from
the package/namespace or a list of 'refer' symbols which can be accessed
without prefix. Anything which could help enable the use of shorter
symbol names and eliminate the need to use prefixes to avoid name
collision would be great. 

Of course, on the other hand, with the exception of longer names, in
over 25 years of Emacs use and especially since the growth in elisp
packages, name collision is something I rarely run into, so the current
status quo does at least seem to work and completion mechanisms have
evolved to make completing with large numbers of candidates having the
same prefix work well and you do tend to get use to the name 'noise'.   

Re: Document that symbol prefix "my-" (or other) should be left for users

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > I'd love to have real namespace support in elisp.

The symbol-aliasing feature was supposed to give us that, but a little
more work is needed.  Would anyone like to finish this?

-- 
Dr Richard Stallman (https://stallman.org)
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)