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

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 26564 in the body.
You can then email your comments to 26564 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Kaushal Modi <kaushal.modi <at> gmail.com>
To: "bug-gnu-emacs <at> gnu.org" <bug-gnu-emacs <at> gnu.org>
Subject: Document that only functions and not variables can end with "-p"
Date: Wed, 19 Apr 2017 15:47:06 +0000

[Message part 1 (text/plain, inline)]

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

[Message part 2 (text/html, inline)]

Message #8 received at 26564 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Kaushal Modi <kaushal.modi <at> gmail.com>
Cc: 26564 <at> debbugs.gnu.org
Subject: Re: bug#26564: Document that only functions and not variables can end
 with "-p"
Date: Wed, 19 Apr 2017 19:08:31 +0300

> From: Kaushal Modi <kaushal.modi <at> 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.

Message #11 received at 26564 <at> debbugs.gnu.org (full text, mbox):

From: Kaushal Modi <kaushal.modi <at> gmail.com>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 26564 <at> debbugs.gnu.org
Subject: Re: bug#26564: Document that only functions and not variables can end
 with "-p"
Date: Wed, 19 Apr 2017 16:22:39 +0000

[Message part 1 (text/plain, inline)]

On Wed, Apr 19, 2017 at 12:08 PM Eli Zaretskii <eliz <at> 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 <at> 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

[Message part 2 (text/html, inline)]

Message #14 received at 26564 <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: Kaushal Modi <kaushal.modi <at> gmail.com>, 26564 <at> debbugs.gnu.org
Subject: RE: bug#26564: Document that only functions and not variables can end
 with "-p"
Date: Wed, 19 Apr 2017 10:26:53 -0700 (PDT)

> 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.

Message #17 received at 26564 <at> debbugs.gnu.org (full text, mbox):

From: Michael Heerdegen <michael_heerdegen <at> web.de>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 26564 <at> debbugs.gnu.org, Kaushal Modi <kaushal.modi <at> gmail.com>
Subject: Re: bug#26564: Document that only functions and not variables can end
 with "-p"
Date: Wed, 19 Apr 2017 23:44:12 +0200

Drew Adams <drew.adams <at> 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.

Message #20 received at 26564 <at> debbugs.gnu.org (full text, mbox):

From: Michael Heerdegen <michael_heerdegen <at> web.de>
To: Kaushal Modi <kaushal.modi <at> gmail.com>
Cc: 26564 <at> debbugs.gnu.org, Eli Zaretskii <eliz <at> gnu.org>
Subject: Re: bug#26564: Document that only functions and not variables can end
 with "-p"
Date: Wed, 19 Apr 2017 23:49:16 +0200

Kaushal Modi <kaushal.modi <at> 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.

Message #23 received at 26564 <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: Michael Heerdegen <michael_heerdegen <at> web.de>
Cc: 26564 <at> debbugs.gnu.org, Kaushal Modi <kaushal.modi <at> gmail.com>
Subject: RE: bug#26564: Document that only functions and not variables can end
 with "-p"
Date: Wed, 19 Apr 2017 15:01:04 -0700 (PDT)

> > 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.

Message #26 received at 26564 <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: Michael Heerdegen <michael_heerdegen <at> web.de>, Kaushal Modi
 <kaushal.modi <at> gmail.com>
Cc: 26564 <at> debbugs.gnu.org
Subject: RE: bug#26564: Document that only functions and not variables can end
 with "-p"
Date: Wed, 19 Apr 2017 15:04:59 -0700 (PDT)

> > -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).

Message #29 received at 26564 <at> debbugs.gnu.org (full text, mbox):

From: Michael Heerdegen <michael_heerdegen <at> web.de>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 26564 <at> debbugs.gnu.org, Kaushal Modi <kaushal.modi <at> gmail.com>
Subject: Re: bug#26564: Document that only functions and not variables can end
 with "-p"
Date: Thu, 20 Apr 2017 00:18:32 +0200

Drew Adams <drew.adams <at> 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.

Message #32 received at 26564 <at> debbugs.gnu.org (full text, mbox):

From: Michael Heerdegen <michael_heerdegen <at> web.de>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 26564 <at> debbugs.gnu.org, Kaushal Modi <kaushal.modi <at> gmail.com>
Subject: Re: bug#26564: Document that only functions and not variables can end
 with "-p"
Date: Thu, 20 Apr 2017 00:23:30 +0200

Drew Adams <drew.adams <at> 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.

Message #35 received at 26564 <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: Michael Heerdegen <michael_heerdegen <at> web.de>
Cc: 26564 <at> debbugs.gnu.org, Kaushal Modi <kaushal.modi <at> gmail.com>
Subject: RE: bug#26564: Document that only functions and not variables can end
 with "-p"
Date: Wed, 19 Apr 2017 15:28:51 -0700 (PDT)

> > 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.

Message #38 received at 26564 <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: Michael Heerdegen <michael_heerdegen <at> web.de>
Cc: 26564 <at> debbugs.gnu.org, Kaushal Modi <kaushal.modi <at> gmail.com>
Subject: RE: bug#26564: Document that only functions and not variables can end
 with "-p"
Date: Wed, 19 Apr 2017 18:42:15 -0700 (PDT)

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

Message #41 received at 26564 <at> debbugs.gnu.org (full text, mbox):

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Kaushal Modi <kaushal.modi <at> gmail.com>
Cc: 26564 <at> debbugs.gnu.org, Eli Zaretskii <eliz <at> gnu.org>
Subject: Re: bug#26564: Document that only functions and not variables can
 end with "-p"
Date: Sat, 12 Oct 2019 22:27:17 +0200

Kaushal Modi <kaushal.modi <at> 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

Message #48 received at 26564 <at> debbugs.gnu.org (full text, mbox):

From: Kaushal Modi <kaushal.modi <at> gmail.com>
To: Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: 26564 <at> debbugs.gnu.org, Eli Zaretskii <eliz <at> gnu.org>
Subject: Re: bug#26564: Document that only functions and not variables can end
 with "-p"
Date: Sat, 12 Oct 2019 16:47:20 -0400

[Message part 1 (text/plain, inline)]

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

> Kaushal Modi <kaushal.modi <at> 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!

>

[Message part 2 (text/html, inline)]

Message #51 received at 26564 <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: Lars Ingebrigtsen <larsi <at> gnus.org>, Kaushal Modi <kaushal.modi <at> gmail.com>
Cc: 26564 <at> debbugs.gnu.org
Subject: RE: bug#26564: Document that only functions and not variables can end
 with "-p"
Date: Sat, 12 Oct 2019 23:18:40 +0000 (UTC)

> +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.

Message #54 received at 26564 <at> debbugs.gnu.org (full text, mbox):

From: Richard Stallman <rms <at> gnu.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 26564 <at> debbugs.gnu.org, larsi <at> gnus.org, kaushal.modi <at> gmail.com
Subject: Re: bug#26564: Document that only functions and not variables can end
 with "-p"
Date: Sun, 13 Oct 2019 21:50:34 -0400

[[[ 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)

Message #57 received at 26564 <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: rms <at> gnu.org
Cc: 26564 <at> debbugs.gnu.org, larsi <at> gnus.org, kaushal.modi <at> gmail.com
Subject: RE: bug#26564: Document that only functions and not variables can end
 with "-p"
Date: Mon, 14 Oct 2019 02:22:42 +0000 (UTC)

> -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').

Message #60 received at 26564 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: rms <at> gnu.org
Cc: 26564 <at> debbugs.gnu.org, larsi <at> gnus.org, drew.adams <at> oracle.com,
 kaushal.modi <at> gmail.com
Subject: Re: bug#26564: Document that only functions and not variables can end
 with "-p"
Date: Mon, 14 Oct 2019 10:21:11 +0300

> From: Richard Stallman <rms <at> gnu.org>
> Date: Sun, 13 Oct 2019 21:50:34 -0400
> Cc: 26564 <at> debbugs.gnu.org, larsi <at> gnus.org, kaushal.modi <at> 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.

Message #63 received at 26564 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 26564 <at> debbugs.gnu.org, larsi <at> gnus.org, rms <at> gnu.org, kaushal.modi <at> gmail.com
Subject: Re: bug#26564: Document that only functions and not variables can end
 with "-p"
Date: Mon, 14 Oct 2019 10:24:36 +0300

> From: Drew Adams <drew.adams <at> oracle.com>
> Cc: 26564 <at> debbugs.gnu.org, larsi <at> gnus.org, kaushal.modi <at> 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.

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.