bug#26564: Document that only functions and not variables can end with "-p"

bug#26564: Document that only functions and not variables can end with "-p"

[Kaushal Modi]

[-- Attachment #1: Type: text/plain, Size: 1195 bytes --]

The discussion on whether variables should end in "-p" came up few time on
emacs-devel, at least the ones I was part of:

1. https://lists.gnu.org/archive/html/emacs-devel/2016-07/msg00734.html
2. http://lists.gnu.org/archive/html/emacs-devel/2017-04/msg00540.html

Doing a rudimentary search in emacs/lisp/ code-base shows a sign of an
undocumented convention that predicate functions, functions that return
either nil or non-nil can end in "-p" (if the function name is multi-word,
like nested-alist-p), or just "p" (if the function name is a single word,
like stringp).

I ran ag[1] in emacs/lisp:

1. 1511 matches -- defuns and defsubsts ending in -p -- ag
'def(un|subst)\s+[^ ]+-p\s+' --stats
2. 149 matches -- defvars, defconsts and defcustoms ending in -p -- ag
'def(var|const|custom)\s+[^ ]+-p\s+' --stats
3. 65 matches -- Just the user-facing defcustoms -- ag 'defcustom\s+[^
]+-p\s+' --stats

That corroborates that more functions tend to end in "-p" than variables.

This bug report is to make a request to incorporate this unspoken rule as a
rule in the Elisp manual.

What would be the correct section to do so?

[1]: https://github.com/ggreer/the_silver_searcher
-- 

Kaushal Modi

[-- Attachment #2: Type: text/html, Size: 2080 bytes --]

bug#26564: Document that only functions and not variables can end with "-p"

[Eli Zaretskii]

> From: Kaushal Modi <kaushal.modi@gmail.com>
> Date: Wed, 19 Apr 2017 15:47:06 +0000
> 
> This bug report is to make a request to incorporate this unspoken rule as a rule in the Elisp manual.
> 
> What would be the correct section to do so?

"Coding Conventions", of course.

Thanks.

bug#26564: Document that only functions and not variables can end with "-p"

[Kaushal Modi]

[-- Attachment #1: Type: text/plain, Size: 1417 bytes --]

On Wed, Apr 19, 2017 at 12:08 PM Eli Zaretskii <eliz@gnu.org> wrote:

> > What would be the correct section to do so?
>
> "Coding Conventions", of course.
>

Please review this patch:

From 9749603b7c3ba45c9c81f9624d6dc42f740aee39 Mon Sep 17 00:00:00 2001
From: Kaushal Modi <kaushal.modi@gmail.com>
Date: Wed, 19 Apr 2017 12:20:05 -0400
Subject: [PATCH] Document convention to reserve "p" or "-p" suffix for
 predicate fns

* doc/lispref/tips.texi (Coding Conventions): The "p" or "-p" suffix
  should be used for only predicate functions, and not
  variables.  (Bug#26564)
---
 doc/lispref/tips.texi | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/doc/lispref/tips.texi b/doc/lispref/tips.texi
index 4e2a0fad1f..ec76fcb5ce 100644
--- a/doc/lispref/tips.texi
+++ b/doc/lispref/tips.texi
@@ -154,7 +154,9 @@ Coding Conventions
 condition is true or false, give the function a name that ends in
 @samp{p} (which stands for ``predicate'').  If the name is one word,
 add just @samp{p}; if the name is multiple words, add @samp{-p}.
-Examples are @code{framep} and @code{frame-live-p}.
+Examples are @code{framep} and @code{frame-live-p}.  This predicate
+suffix should not be used in variable names (i.e., you might name a
+variable @code{foo-feature} instead of @code{foo-feature-p}).

 @item
 If the purpose of a variable is to store a single function, give it a
-- 
2.11.0


-- 

Kaushal Modi

[-- Attachment #2: Type: text/html, Size: 2239 bytes --]

bug#26564: Document that only functions and not variables can end with "-p"

[Drew Adams]

> The discussion on whether variables should end in "-p" came up few time on emacs-devel, at least the ones I was part of:
> 
> 1. https://lists.gnu.org/archive/html/emacs-devel/2016-07/msg00734.html
> 2. http://lists.gnu.org/archive/html/emacs-devel/2017-04/msg00540.html
> 
> Doing a rudimentary search in emacs/lisp/ code-base shows a sign of an undocumented convention that predicate functions, functions that return either nil or non-nil can end in "-p" (if the function name is multi-word, like nested-alist-p), or just "p" (if the function name is a single word, like stringp).
> 
> I ran ag[1] in emacs/lisp:
> 
> 1. 1511 matches -- defuns and defsubsts ending in -p -- ag 'def(un|subst)\s+[^ ]+-p\s+' --stats
> 2. 149 matches -- defvars, defconsts and defcustoms ending in -p -- ag 'def(var|const|custom)\s+[^ ]+-p\s+' --stats  
> 3. 65 matches -- Just the user-facing defcustoms -- ag 'defcustom\s+[^ ]+-p\s+' --stats
> 
> That corroborates that more functions tend to end in "-p" than variables.

A better measure would be # of `-p' vs number of NON-`-p',
for both functions and variables.  But I'm sure that the
same result holds: far more `-p' functions than `-p' vars.

Stefan, at least, has actively discouraged the use of vars
with `-p' names, in emacs-devel.  That could partly explain
the numbers.  Also, there is nothing in the Elisp manual
coding conventions about `-p' for var names, so users
wouldn't get the idea to do that from the manual.  That too
could partly explain the numbers.

> This bug report is to make a request to incorporate this unspoken rule as a rule in the Elisp manual.
> 
> What would be the correct section to do so?
>
> [1]: https://github.com/ggreer/the_silver_searcher

FWIW, I disagree with a guideline to not name Boolean vars
using `-p'.

1. Variables and functions are already in separate spaces -
they can be examined/found separately (`boundp' vs `fboundp').  

What do you hope to gain by outlawing/discouraging `-p' for 
Boolean variable names?  It cannot be to avoid confusing a
variable and a function, since the those kinds of animal are
already separate in Emacs Lisp.

2. A variable is, abstractly (e.g., in a formal abstract
data type), a nullary function.  It makes just as much
sense to name a Boolean variable using `*-p' as it does
to name a Boolean function using that convention.

Just one opinion.  Stefan disagrees, for instance (but
with no reasons given).

3. Is there a proposal for a _different_ naming convention
for Boolean variables?  I'd argue that we should have some
such a naming convention.  And I'd argue that it should be
different for options and non-option variables.

I use `-flag' for Boolean options and `-p' for Boolean
non-option variables.  (I did  not come up with the `-flag'
convention, BTW.  Someone else did, long ago.  I thought it
was a GNU Emacs convention, (maybe it was?) so I stuck to it.
Stefan is not a fan of `-flag' (or any naming convention for
vars).

4. There should be some easy way to ask for help on Boolean
variables.  Better yet would be a way to ask for help on
a user option, filtering by defcustom type.

FWIW, I have code that does that.  It provides help commands
that let you show the help for things based on different 
criteria, and for options that includes the custom type.

You can match the type in different ways, depending on the
prefix argument:

 - None:      OPTION is defined with TYPE or a subtype of TYPE.
              TYPE is a regexp.

 - `C-u':     OPTION is defined with TYPE or a subtype of TYPE,
                or its current value is compatible with TYPE.
              TYPE is a type definition or its first symbol.

 - Negative:  OPTION is defined with TYPE (exact match).
              TYPE is a regexp.

 - Positive:  OPTION is defined with TYPE,
                or its current value is compatible with TYPE.
              TYPE is a type definition or its first symbol.

 - Zero:      OPTION is defined with TYPE or a subtype of TYPE.
              TYPE is a type definition or its first symbol.

 - `C-u C-u': OPTION is defined with TYPE (exact match).
              TYPE is a type definition or its first symbol.

_Without_ such a capability, it should be possible, at a
minimum, to get only Boolean options, using a name-pattern
match.

Again, just one opinion.

bug#26564: Document that only functions and not variables can end with "-p"

[Michael Heerdegen]

Drew Adams <drew.adams@oracle.com> writes:

> 3. Is there a proposal for a _different_ naming convention
> for Boolean variables?  I'd argue that we should have some
> such a naming convention.  And I'd argue that it should be
> different for options and non-option variables.

That's a good point indeed.

An alternative to "-p" would be "is-", like `foo-is-negative'.

Not using -p would also have an advantage: you could distinguish boolean
variables from variables bound to a predicate function.


Michael.

bug#26564: Document that only functions and not variables can end with "-p"

[Michael Heerdegen]

Kaushal Modi <kaushal.modi@gmail.com> writes:

> -Examples are @code{framep} and @code{frame-live-p}.
> +Examples are @code{framep} and @code{frame-live-p}.  This predicate
> +suffix should not be used in variable names (i.e., you might name a
> +variable @code{foo-feature} instead of @code{foo-feature-p}).

I think we should not discourage naming variables bound to a predicate
"-p".  I guess you only mean "boolean variables" here?


Michael.

bug#26564: Document that only functions and not variables can end with "-p"

[Drew Adams]

> > 3. Is there a proposal for a _different_ naming convention
> > for Boolean variables?  I'd argue that we should have some
> > such a naming convention.  And I'd argue that it should be
> > different for options and non-option variables.
> 
> That's a good point indeed.
> 
> An alternative to "-p" would be "is-", like `foo-is-negative'.

Not great for cases where "has-" would be more appropriate (and
vice versa, for cases where "is-" would be more appropriate).
Not good for lots of other cases too.

E.g., `box-cursor-when-idle-p' or `use-foo-bar-p' or
`remove-foo-props-p' or `iac1-was-cycling-p' or
`foo-names-only-p' or `hl-line-when-idle-p'?

I suggest we stay away from helper verbs (or even any words).
Verbs, in particular, can be different for singular and plural
(e.g. `fancy-candidates-p').

> Not using -p would also have an advantage: you could distinguish
> boolean variables from variables bound to a predicate function.

How is it difficult to distinguish those if `-p' is used for
both?

It's true that in some (very few) contexts just looking at
"'foo-p" in some code might not let you know whether `foo-p'
is a variable or a function (or is both), but it is trivial
to find out which is the case, for any symbol that is already
defined as a variable or a function.

bug#26564: Document that only functions and not variables can end with "-p"

[Drew Adams]

> > -Examples are @code{framep} and @code{frame-live-p}.
> > +Examples are @code{framep} and @code{frame-live-p}.  This predicate
> > +suffix should not be used in variable names (i.e., you might name a
> > +variable @code{foo-feature} instead of @code{foo-feature-p}).
> 
> I think we should not discourage naming variables bound to a predicate
> "-p".  I guess you only mean "boolean variables" here?

I _would_ discourage that.

And I'd promote the practice of naming variables expected to
be bound to a Boolean _value_ with suffix `-p'.

Just as a predicate _returns_ a Boolean value, so does a
Boolean-valued variable.

A variable whose value is a _predicate_ I'd name something
like `foo-predicate' or `foo-pred' or even `foo-function'
(the last one following the current convention).

bug#26564: Document that only functions and not variables can end with "-p"

[Michael Heerdegen]

Drew Adams <drew.adams@oracle.com> writes:

> A variable whose value is a _predicate_ I'd name something like
> `foo-predicate' or `foo-pred' or even `foo-function' (the last one
> following the current convention).

For "exported" defvar'd variables I agree.

bug#26564: Document that only functions and not variables can end with "-p"

[Michael Heerdegen]

Drew Adams <drew.adams@oracle.com> writes:

> I suggest we stay away from helper verbs (or even any words).
> Verbs, in particular, can be different for singular and plural
> (e.g. `fancy-candidates-p').

It's a matter of taste.  I like when symbols have names that speak to
me, even when there is no clear rule of how to name them.  The most
important thing is that you see how the binding is intended to be used.


Michael.

bug#26564: Document that only functions and not variables can end with "-p"

[Drew Adams]

> > I suggest we stay away from helper verbs (or even any words).
> > Verbs, in particular, can be different for singular and plural
> > (e.g. `fancy-candidates-p').
> 
> It's a matter of taste.  I like when symbols have names that speak to
> me, even when there is no clear rule of how to name them.

Yes.  But here we're talking about coming up with a general
naming convention (or not doing so).

> The most important thing is that you see how the binding is
> intended to be used.

Agreed.

bug#26564: Document that only functions and not variables can end with "-p"

[Drew Adams]

BTW, another short, simple suffix to indicate a Boolean value
or test is `?'.  Scheme conventionally uses that for predicates,
for example.

bug#26564: Document that only functions and not variables can end with "-p"

[Lars Ingebrigtsen]

Kaushal Modi <kaushal.modi@gmail.com> writes:

> Subject: [PATCH] Document convention to reserve "p" or "-p" suffix for
>  predicate fns
>
> * doc/lispref/tips.texi (Coding Conventions): The "p" or "-p" suffix
>   should be used for only predicate functions, and not
>   variables.  (Bug#26564)

I've now applied this to Emacs 27.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

bug#26564: Document that only functions and not variables can end with "-p"

[Kaushal Modi]

[-- Attachment #1: Type: text/plain, Size: 439 bytes --]

On Sat, Oct 12, 2019, 4:27 PM Lars Ingebrigtsen <larsi@gnus.org> wrote:

> Kaushal Modi <kaushal.modi@gmail.com> writes:
>
> > Subject: [PATCH] Document convention to reserve "p" or "-p" suffix for
> >  predicate fns
> >
> > * doc/lispref/tips.texi (Coding Conventions): The "p" or "-p" suffix
> >   should be used for only predicate functions, and not
> >   variables.  (Bug#26564)
>
> I've now applied this to Emacs 27.
>

Thank you!

>

[-- Attachment #2: Type: text/html, Size: 1096 bytes --]

bug#26564: Document that only functions and not variables can end with "-p"

[Drew Adams]

> +This predicate
> +suffix should not be used in variable names (i.e., you might name a
> +variable @code{foo-feature} instead of @code{foo-feature-p}).

FWIW, I disagree with this new "convention".

1. There's no need for it.  What does it protect?

2. And using suffix `-p' can make clear the meaning
   and use of a variable, regardless of whether it's
   a formal parameter, a defvar, or a let variable.

bug#26564: Document that only functions and not variables can end with "-p"

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

-p is used in function names.
For a variable, it is better to end in -flag.

-- 
Dr Richard Stallman
Founder, Free Software Foundation (https://gnu.org, https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

bug#26564: Document that only functions and not variables can end with "-p"

[Drew Adams]

> -p is used in function names.
> For a variable, it is better to end in -flag.

`-flag' has been used only, AFAIK, for user options.

---

What I use, FWIW:

* `-flag' for user options.  (I'm about the only
one who does this anymore, it seems.)

* `-p' for non-option variables whose values
  are used just as Booleans (`nil', non-`nil').

* No suffix for non-option variables whose values
  are used other than just as Booleans (`nil',
  non-`nil').

bug#26564: Document that only functions and not variables can end with "-p"

[Eli Zaretskii]

> From: Richard Stallman <rms@gnu.org>
> Date: Sun, 13 Oct 2019 21:50:34 -0400
> Cc: 26564@debbugs.gnu.org, larsi@gnus.org, kaushal.modi@gmail.com
> 
> -p is used in function names.
> For a variable, it is better to end in -flag.

I provided that example, along with others, in the manual.

bug#26564: Document that only functions and not variables can end with "-p"

[Eli Zaretskii]

> From: Drew Adams <drew.adams@oracle.com>
> Cc: 26564@debbugs.gnu.org, larsi@gnus.org, kaushal.modi@gmail.com
> 
> > -p is used in function names.
> > For a variable, it is better to end in -flag.
> 
> `-flag' has been used only, AFAIK, for user options.

User options are variables, and I see no reason not to use it for
variables that are not user options.

If you want to see the text that is now actually in the manual, please
use the cgit interface at savannah.  I suggest to do that before
arguing further about this.