RE: changing function signatures and no library version # => must use too-general test

[Drew Adams]

    >     I don't know specifically what happened with
    >     help-insert-xref-button,
    >     but it's prety common to change a function's list of
    >     arguments without
    >     subsantially changing its body and/or its conceptual
    >     meaning, in which
    >     case it will usually makes more sense to keep the same name.

    > Too bad for Emacs users. No, I don't see how that usually
    > makes more sense, whether it is common or not.

    In most coding practices, there is this thing about choosing
    your function names based on what they do.

A good, general rule.

    > Annoyance to developers is important, but it is not as
    > important as clean
    > software and clear software maintenance.

    It is *specifically* for clarity of the code and clear software
    maintenance that function names should be chosen correctly,
    without having to worry about previously used names.

Do I detect a little mauvais foi, or do you really believe that is what this
is about?

1. You won't find an argument against that from me, at that level of
abstraction. As you know, I've argued long and hard for getting function
names to accurately reflect what the functions do. Think back to the
discussion of the myriad different names for exiting view mode, none of
which were very "parlant". Likewise, menu names...

2. However, your argument is at too high an abstraction level. There is not
one, single, acceptable name for a given function. For the example given,
`help-insert-xref-button', there are plenty of acceptable alternatives, even
given the constraints of starting with "help" and including "xref-button":
`help-xref-button-insert', `help-insert-an-xref-button',
`help-add-xref-button', and so on.

3. Your abstract argument is also presented in stark isolation. It is
inappropriate to consider only one (good, general) software-engineering rule
(heuristic) and elevate it to the status of something inviolable. Such rules
need to be applied, and their application judged appropriate or not,
together, in combination, in a particular concrete context. The guidelines I
discussed are also important.

In a concrete, practical context there are tradeoffs to consider - for
example, is it more important that the name be exactly
`href-insert-xref-button' (because it accurately describes the function) or
is it more important to use a different name because that name is already
used for something different (in another Emacs version that is likely to
still be in use). Emacs developers might never get confused or bothered by
the existence of two different `href-insert-xref-button' functions because
they generally work with only one Emacs version, but others who work with
multiple versions will.

When you add "without having to worry about previously used names", you
violate the utility of the good guideline you promote. It's about balancing
such general rules, in context, together. It's not about promoting one's
favorite rule du jour and trying to sneak in an addendum that it is
inviolate even in the face of another rule (in all contexts, no less).

Of course names should be as accurate as possible, but yes, we do have to
worry also about previously used names much of the time. Legacy is something
that software engineering rules need to deal with. Only one-off school
projects can ignore legacy (there is none). It's ugly and mundane, no doubt,
but it's also part of what makes software development interesting.

4. Also to be measured in such a combined judgement are mitigating factors:
A function name is one way to document a function's meaning or behavior, but
it is not the only way; a function name that does not communicate
sufficiently accurately what the function is about can be supplemented by
documentation (the manual), a doc string, and source-code comments.