naming functions [was: Ibuffer: w and B default to buffer at current line]

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

> > > > Yes, of course.  But as I pointed out, the case at 
> > > > hand has nothing to do with DWIM.
> > >
> > > I disagree.
> >
> > And your reason is?  A user _explicitly specifies_
> > which to use, of the behaviors the command supports.
> > How is that guess-what-I-mean-and-do-it?
> 
> See what John wrote.  The issue at hand is broader than what 
> you interpreted it to be.

Please point to something that John said that you think speaks
for you here and answers the question: What is your reason for
thinking that simply having a prefix arg choose an alternative
behavior is DWIM?

> > Is `forward-char` a DWIM command, simply because it can
> > move different distances depending on a prefix arg?

Your answer to that is yes?  If so, why?

----

Wrt command (and other function) names (John's point):
Name choices are limited.  Doc strings are there to
clarify things.

John:

Is `forward-char' a bad name, because with a negative
prefix arg it moves backward?  Is it a bad name because
it is singular and a prefix arg > 1 moves further than
one position?

Should the name have been `move-char' or `move-chars'?
If so, then what about binding forward and backward
default behaviors to different keys, `C-f' and `C-b'?

I think (hope) you get the point.  A function name only
goes so far toward indicating what the function does.
If a prefix arg to a command chooses alternative behavior,
then it would often be cumbersome and _less_ clear to
users, to use a name that tries to summarize all of the behaviors.

Finally, adding `dwim' to a command name is really just
punting - pretty much all of the time.  By definition, it
says almost nothing about what the command does.  In the
worst case it says, loud and clear, "I can't give a good
name to this command.  I can barely describe it in the
doc string."

Using `dwim' in a command name tells the user only this:

  This command has multiple behaviors, some of which you
  might be able to control, and some of which might be
  determined otherwise by the use context.  See the doc
  string for what this command really does.

Consider these vanilla Emacs commands, which comment and
uncomment the region: `comment-region', `comment-dwim',
`comment-or-uncomment-region', `comment-line'.

They all comment & uncomment the region, but in different
ways.  None of those names is great, and none of those
commands is more or less DWIMish than the others.

OK, such naming is historical.  `comment-region' was
first.  `comment-or-uncomment-region' was added to
provide a slightly different behavior.  Its name more
clearly points out that it can be used to UNcomment.

(It is unfortunate, IMO, that more users do not think
to use `comment-region', including for UNcommenting,
because it is a great command.  Its uncommenting
behavior is superior to that of `comment-dwim',
`comment-line', and `comment-or-uncomment-region'.
But yes, its name does not advertise the fact that
it can uncomment.)

Presumably, John, between the two names `comment-region'
and `comment-or-uncomment-region' you would favor the
latter.  I would too, and it is much better than
`comment-dwim', which says only, "Sorry - see the doc
string to find out what this command does."

But consider that there are _many possible_ commands
that comment or uncomment region text.  The above are
all in vanilla Emacs, and I and others have come up
with still other such commands.  (I use my command
`comment-region-lines', which is like `comment-region',
except that it (un)comments whole lines that are
(at least partly) included in the region.)

Emacs is made to end up with multiple such commands.
They cannot EACH be called `comment-or-uncomment-region'
or even `comment-dwim'.

And to name each of them in a way that would describe
its behavior more clearly and _distinguish it from the
others_ would result in long and incomprehensible names.

And then, when another such command is defined (in Emacs
proper or in a 3rd-party library), some or all of them
might (logically) need to be REnamed, to properly
distinguish all of the meanings.

This might be seen as less of a problem if you ignore
the wider Emacs world outside core Emacs development.
But it is nevertheless a difficulty _inherent in the
nature_ of something like Emacs.

Names only go so far, toward conveying behavior/meaning.
And naming is historical.  And labels such as "dwim' do
NOT help to convey the specific meaning of a command.
They just punt to the doc string.

So while this general principle is a good one:

  A function's name should describe its behavior,
  and none of the behavior should be hidden behind a
  misleading name.

In practice, in a context like Emacs, things are more
complex.

This is particularly the case when it comes to commands.
And particularly when there are two commands, bound to
keys, that are more or less symmetrical - such as
`forward-char' and `backward-char'.  Each is, in fact,
a command that moves point one or more chars backward
or forward.  Neither moves only forward or only backward.
But we want 2 different commands, for 2 different keys.

In Emacs, the command naming policy has generally been
this: Name a command for its _default_ behavior, and
describe all of the alternative behaviors in the doc
string.  That works pretty well, in general.

Yes, the default behavior does NOT tell the whole
story - by definition.  But it is often, even
generally, the case that a command name _cannot_
usefully tell the whole story.  (That does not imply
that the command behavior is ill-conceived.)

In particular, putting `dwim' in a command name is a
poor cop-out.  The default behavior should generally
be used for the command name, even for a DWIM command.

(On the other hand, if it is simple to describe the
various behaviors in the name, then that can sometimes
be better.  `comment-or-uncomment-region' is better
than just `comment-region').

Some might think that putting `dwim' in a command
name is important for advertising the fact that there
_are_ multiple behaviors.  I don't buy that argument.
It is just another Look-ma-no-hands!, Tu-m'as-vu !
exclamation, akin to NEW!!!  IMPROVED!!!  SUPER!!!!

There might be a temporary effect, for a new command
named `*-dwim-*', that it attracts attention and gives
the (mistaken) impression that other commands do _not_
have multiple behaviors or do _not_ have behavior that
depends on the context.  Over time, such a name is
seen for what it is: "dwim" in the name is just noise.

We should avoid lazily naming commands with `dwim'.
It's the equivalent of the Marketing-Speak "smart":

  smart car, smart phone, smart train, smart tech,
  smart goal, smart tuition, smart exchange, smart
  growth, smart manufacturing, smart health, smart
  grid, smart cloud, smart design, smart card, smart
  package, smart kit, smart keyboard, smart material,
  smart TV,...

Nothing is duller.  Nothing says less that is helpful.
DWIM, like WYSIWYG, is a clever acronym.  But it
doesn't say much, if anything.