Quantcast

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

classic Classic list List threaded Threaded
12 messages Options
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

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

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


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?

--

Kaushal Modi

Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

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

Eli Zaretskii
> From: Kaushal Modi <[hidden email]>
> 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.



Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

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

Kaushal Modi
On Wed, Apr 19, 2017 at 12:08 PM Eli Zaretskii <[hidden email]> 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 <[hidden email]>
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

Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

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

Drew Adams
In reply to this post by Kaushal Modi
> 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.



Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

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

Michael Heerdegen
Drew Adams <[hidden email]> 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.



Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

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

Michael Heerdegen
In reply to this post by Kaushal Modi
Kaushal Modi <[hidden email]> 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.



Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

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

Drew Adams
In reply to this post by Michael Heerdegen
> > 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.



Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

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

Drew Adams
In reply to this post by Michael Heerdegen
> > -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).



Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

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

Michael Heerdegen
Drew Adams <[hidden email]> 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.



Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

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

Michael Heerdegen
In reply to this post by Drew Adams
Drew Adams <[hidden email]> 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.



Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

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.



Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

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.



Loading...