bug#25581: 25.1; Incorrect statement in (elisp) `Hooks'

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

> >> +If the name of the variable ends in @samp{-predicate} or
> >> +@samp{-function} (singular) then its value must be a function, not a
> >
> > Is this the (new) policy, adding the suffix `-predicate'?
> > In my previous comments I was sticking to the old policy, and
> > pointing out that `isearch-filter-predicate', now that it is
> > being advised here and there with `add-function', is being used
> > as a hook, and so it should be named accordingly, as `*-function'.
> 
> Not sure, I was under the impression that -predicate is the same idea as
> -function, with the added implication about the return value's meaning.
> No idea if this is "new" or not.

It's one thing to say that a Boolean function is, in effect, a
predicate.  It's another thing to extend the convention of names
that end in `-function' to apply to names that end in `-predicate'.

Such a convention has never been pronounced before, AFAIK.
I don't think we should make convention policy this way.

Instead, I suggested in my report that the example I know about,
`isearch-filter-predicate' is misnamed, precisely because it
acts like a hook but is not named following the convention.
It should be named `-function', IMO.

Whether or not it is easy to rename it now (I think it's possible
to deprecate the old name), the fact that it is misnamed should
not, by itself, start a spread of `-predicate' as yet another
possible hook-name suffix.  If someone mistakenly adds another
variable that is, in its behavior a hook, and it has suffix
`-fn' or `-pred' or `-test', should we then willy nilly update
the doc to extend the convention some more?

> > But the addition of nadvice.el and subsequent encouragement
> > of advising functions with it applies to all functions.  It in
> > effect makes every function-valued variable into a hook.
> 
> Yes.
> 
> > Can or should users expect that such variables will by
> > convention have such a conventional suffix?
> 
> I guess?

It's not my call, and as I said, I don't know what I think
about this.  I tend to lean at the moment toward saying
that if we are advising people to `advice-add' variables
whose value is expected to always be a function, and if
we are calling that a hook of sorts, then we should stick
with recommending a simple convention of suffix `-function'.

I also think that we should probably point out explicitly
somewhere why we have these naming conventions: to facilitate
(human) readability.  A variable whose name ends in
`-function' is conventionally such a hook.  That means that
just seeing such a name makes us likely to think it is
(whether or not it really is - it could be a variable whose
value is not necessarily a function).  It's an aid to reading,
with no guarantees about how reliable/accurate it is.

> > Now, since you can apply `add-function' to any function, it
> > can happen that someone defines a variable - of whatever
> > name - whose value can be a (single) function or nil (or
> > a number or a symbol or a character or...).  In a general
> > sense, since the value CAN be a function, someone could
> > call such a variable a "hook", if s?he wants.
> >
> > But that is, I think, NOT what we are talking about in
> > this doc.  We are talking here about naming conventions
> > for variables whose values are either (1) a function
> > whose name ends in `-function' (or `-predicate'?) and
> > whose value MUST BE a function or (2) a list of functions
> > (normal & abnormal hooks, for which you can use `add-hook').
> 
> Hmm, I'm not sure if making this division is helpful.  I do think we
> need some kind of name for these kind of "hooks".  Just not sure what it
> should be...

Please read my last paragraph that you just cited again.
That's my point.  Those are exactly the naming conventions
we've had, up till now. IMO they are the naming conventions
we should still have.

A variable whose value can be anything, including possibly a
function, is not a hook in the sense introduced by our naming
conventions.

Someone might want to call it a hook because _when its value
is a function_, if code invokes that function then yes, it
hooks into that function's code.

But that's a far cry from the conventions talked about here,
which are strict (clear) about what they apply to.  If a
variable can be anything then its name can be anything, and
whether or not it might sometimes have a function value and
be invoked is not a reason to dilute the helpful conventions.

The point of such a convention (see above) is to help you
read code, without analyzing it in detail to see what the
use of such a variable is.

If someone uses the a name `*-function' its a pretty safe
bet that its value _is_ a function and that the code invokes
it somewhere.

If we start applying such a name to anything and everything
that might sometimes have a function value then its power
to help reading is reduced.  Then, for EVERY variable named
`*-function' a reader will need to read all of the code
carefully, to see whether and where it might have a function
value.

It's better to have a good, quick first approximation based
on the name, so that even without scrutinizing the code you
can suppose that the value is a function.

Otherwise, there is little point in having such a convention.