RE: master baf331e 3/3: Rename replace-in-string to string-replace

[Drew Adams <drew.adams@oracle.com>]

>  >> Do we need a (defalias 'string-replace-regexp
>  >> 'replace-regexp-in-string)?
> 
>  Lars> I'm not very enthusiastic about adding noun-verb aliases for the
>  Lars> verb-noun functions we already have.  It makes reading code more
>  Lars> confusing when we have several names for the same thing.
> 
> I agree, but in this case anyone who finds 'string-replace' is going
> to have a harder time finding 'replace-regexp-in-string'. The two
> functions are twins, they should be easy to find from one another.
> 
>  Lars> Discoverability is an issue, though, and I'm working on that.
> 
> We can always stick cross-references in the respective docstring, but
> people are still going to wonder about the irregular naming.


FWIW - two things to say here, one about the name
`string-replace' and one, more general, about naming.


1. `replace-in-string' is pretty self-explanatory,
certainly more so than `string-replace'.  The latter
makes you think that you're replacing one string with
another (which you are) - but where?  In a buffer? file?
the region?

`string-replace' suggests the same that `replace-string'
suggests.  And we already have `replace-string':
"Replace occurrences of FROM-STRING with TO-STRING."
Now we'll have `replace-string' and `string-replace'?
Is that progress?

IIUC, `replace-in-string' was rejected because of some
incompatibility with XEmacs (name clash?).  If so,
that's too bad, as replacing something within a string
is pretty clear from that name.  And as the something
isn't part in the name, it's pretty straightforward to
guess that it's a substring that's being replaced.

Both `replace-in-string' and `replace-regexp-in-string'
are pretty clear.  `string-replace' and
`string-replace-regexp' not so much.

Just sayin'.  I don't really have a great alternative
here.  (`replace-substring'? `replace-within-string'?
`replace-some-of-string'? `replace-string-substring'?)
If `replace-in-string' is off limits for some reason
then so be it - but too bad.


2. Discoverability is important, yes - very important.
But it's a mistake, IMO, to sacrifice more easily
understood names in favor of less easily understood
names, only because of easier discoverability by
_prefix completion_.  (Again, general argument here -
not about `string-replace'.)

Better to improve completion (use substring or regexp
or fuzzy or ... completion) so that the better names
are more easily discovered using completion.

_Apropos_ should be our guide for discoverability, not
prefix completion.  Our UI (especially completion)
should make it easy to discover a name by its
"components", in whatever order they might appear.

[I have a lot of experience with "apropos" completion,
including ways to match name components/substrings in
arbitrary order.  That's lacking in vanilla Emacs.]

We should not name things with discovery by prefix
completion foremost in mind.  That's a step backward.
If all other things are equal (rare), prefix-oriented
discovery can be nice to have - nothing more.

This point (#2) is not about _what can make_ a name
more understandable.  (There are lots of things to
consider for that.) 

And this point isn't an argument favoring noun-verb
or verb-noun.  This is only to favor understandable
names (however that's judged), and to deal with
discoverability separately, rather than elevating
prefix-completion discoverability as an important
criterion for naming.

And this point says nothing about the value of
naming _consistency_.  That's a different, but
related, topic.