Subject: RE: bug#24353: 25.1.1: looking-back wrong info

From: Drew Adams <[email-masked]>
Date: Fri, 2 Sep 2016 16:59:30 -0700 (PDT)

> > How does this change help Emacs users?
> 
> It forces Emacs Lisp programmers to include the last argument,

It certainly does not.  It does NOT force anything.
It only misleads.  It doesn't even explicitly recommend.

> thus making their code likely faster. Users like faster programs.

The right way to _encourage_ programmers to use it is to
tell them precisely that: "Using LIMIT is recommended - it
typically results in faster code."

Or "strongly recommended".  Or "You're nuts if you omit LIMIT!"
Or whatever other positive or negative encouragement you think
might be most effective and appropriate.

Telling them nothing about this and, instead, just showing a
false signature, does NOT help them.

> > If it is so important that people provide LIMIT then spell
> > that out _explicitly_ in the doc as a recommendation.
> 
> That's very easy to miss.

It's nowhere near as easy to miss as just moving LIMIT before
&optional in the printed (and false) signature.

Anyone getting super serious about the function, and interested
beyond the doc string, will look at the code, and will conclude
that the signature in the doc string must by a typo (erroneous).
And erroneous it is.

An explicit recommendation is quite effective.  It can be as
strong and as noticeable as you like, or as gentle and quiet
as you like.

> And like Eli said, the choice was between this and
> _actually_ changing the signature.

No, that was not the only choice.  The desired change is
(apparently) to pass a strong recommendation message, in
order to affect programmer behavior.  That doesn't happen
just by faking a signature.

If you want to change behavior, let programmers know that -
explicitly.  Telling them the (positive) effect of LIMIT is
the best way to get them to use it.

> I imagine you would like the latter choice even less.

It doesn't really affect me, personally.  But yes, that
would be quite unwise, for Emacs users and code generally.

If it aint broke, don't fix it.  Is it _sufficiently
important_ that code uses LIMIT that you need to break
backward compatibility?  If so, then you have no choice
but to break it.  But that is the question.

> > It should be a no-no to just change the advertized
> > signature of a function, without changing the actual
> > signature (code) and without otherwise changing the doc.
> 
> You have some point there, but mentioning the last argument in the
> docstring would be rather awkward, considering it's absent in the
> advertised signature.

Sorry, but I have no idea what you mean by that.

This doc-string change seems doubly bad, in fact:

1. The signature that is shown is false.

2. We removed this sentence, which was the only suggestion
   related to performance:

   "As a general recommendation, try to avoid using
    `looking-back' wherever possible, since it is slow."

If that vague recommendation is not accurate or is not
strong enough, then replace it with a more accurate or
stronger one.

But don't just say NOTHING about performance and NOTHING
about the effect of LIMIT on performance, if that's what
this is really all about.

Programmers and other users are not dumb "losers".  They
are smart enough to understand what you have to say to
them about LIMIT.  Just say it - explicitly.