unofficial mirror of emacs-devel@gnu.org 
 help / color / mirror / code / Atom feed
* Recommend lexical-binding in Coding Conventions
@ 2020-10-21  1:05 Stefan Kangas
  2020-10-21  4:32 ` Drew Adams
  2020-10-21 13:33 ` Stefan Monnier
  0 siblings, 2 replies; 9+ messages in thread
From: Stefan Kangas @ 2020-10-21  1:05 UTC (permalink / raw)
  To: emacs-devel

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

We don't currently recommend using lexical-binding in our Coding
Conventions (`(elisp) Tips').  Is there some reason for that, or is it
just an oversight?

I would suggest to add it, and have attached a first draft for what it
could look like.

Thoughts?

[-- Attachment #2: 0001-Recommend-lexical-binding-in-Coding-Conventions.patch --]
[-- Type: text/x-diff, Size: 2156 bytes --]

From a2835ab38edcbd583f87998813ebf36abe110165 Mon Sep 17 00:00:00 2001
From: Stefan Kangas <stefan@marxist.se>
Date: Wed, 21 Oct 2020 01:50:50 +0200
Subject: [PATCH] Recommend lexical-binding in Coding Conventions

* doc/lispref/tips.texi (Coding Conventions, Library Headers):
Recommend using lexical-binding.
---
 doc/lispref/tips.texi | 17 +++++++++++------
 1 file changed, 11 insertions(+), 6 deletions(-)

diff --git a/doc/lispref/tips.texi b/doc/lispref/tips.texi
index 5b09b2ccea..6bed53f263 100644
--- a/doc/lispref/tips.texi
+++ b/doc/lispref/tips.texi
@@ -94,6 +94,11 @@ Coding Conventions
 If one prefix is insufficient, your package can use two or three
 alternative common prefixes, so long as they make sense.
 
+@item
+We recommended to enable @code{lexical-binding} in new code, and to
+convert existing Emacs Lisp code to use lexical binding if it doesn't
+already.  @xref{Using Lexical Binding}.
+
 @item
 Put a call to @code{provide} at the end of each separate Lisp file.
 @xref{Named Features}.
@@ -963,7 +968,7 @@ Library Headers
 
 @smallexample
 @group
-;;; foo.el --- Support for the Foo programming language
+;;; foo.el --- Support for the Foo programming language  -*- lexical-binding: t; -*-
 
 ;; Copyright (C) 2010-2020 Your Name
 @end group
@@ -986,14 +991,14 @@ Library Headers
   The very first line should have this format:
 
 @example
-;;; @var{filename} --- @var{description}
+;;; @var{filename} --- @var{description}  -*- lexical-binding: t; -*-
 @end example
 
 @noindent
-The description should be contained in one line.  If the file
-needs a @samp{-*-} specification, put it after @var{description}.
-If this would make the first line too long, use a Local Variables
-section at the end of the file.
+The description should be contained in one line.  If the file needs to
+set more variables in the @samp{-*-} specification, add it after
+@code{lexical-binding}.  If this would make the first line too long, use
+a Local Variables section at the end of the file.
 
   The copyright notice usually lists your name (if you wrote the
 file).  If you have an employer who claims copyright on your work, you
-- 
2.28.0


^ permalink raw reply related	[flat|nested] 9+ messages in thread

* RE: Recommend lexical-binding in Coding Conventions
  2020-10-21  1:05 Recommend lexical-binding in Coding Conventions Stefan Kangas
@ 2020-10-21  4:32 ` Drew Adams
  2020-10-21 13:33 ` Stefan Monnier
  1 sibling, 0 replies; 9+ messages in thread
From: Drew Adams @ 2020-10-21  4:32 UTC (permalink / raw)
  To: Stefan Kangas, emacs-devel

> I would suggest to add it, and have attached a first draft for what it
> could look like.  Thoughts?

Mine:

tl;dr: Just recommend setting var `lexical-binding' to non-nil.
___

1. The recommendation to set variable `lexical-binding'
to non-nil is good.

2. The recommendation to "convert existing Emacs Lisp
code to use lexical binding" is unclear or ambiguous.

Setting the variable to non-nil just makes lexical
binding the default (e.g. for a file), which is what
we should encourage.

#2 can easily be misinterpreted to mean that code
should not use dynamic binding, which would be
misguided, IMO.

There's a reason that Common Lisp and Emacs Lisp have
both kinds of binding.  Both are useful for Lisp, and
dynamic binding has particular usefulness for Emacs
users.

I see no reason for adding #2.  It doesn't mean
anything good, clear, or important, IMO.  #1 suffices,
and is the message to send, I think.

On the other hand, if what you meant by #2 was just
an elaboration of #1, i.e., convert existing code to
work with `lexical-binding' non-nil, then that's OK.

But it's not necessary, as it follows from #1: if you
set `lexical-binding' to non-nil in existing code then
you'll find out what changes you might need to make,
to get it to continue to work well.



^ permalink raw reply	[flat|nested] 9+ messages in thread

* Re: Recommend lexical-binding in Coding Conventions
  2020-10-21  1:05 Recommend lexical-binding in Coding Conventions Stefan Kangas
  2020-10-21  4:32 ` Drew Adams
@ 2020-10-21 13:33 ` Stefan Monnier
  2020-10-21 14:52   ` Drew Adams
  1 sibling, 1 reply; 9+ messages in thread
From: Stefan Monnier @ 2020-10-21 13:33 UTC (permalink / raw)
  To: Stefan Kangas; +Cc: emacs-devel

> +@item
> +We recommended to enable @code{lexical-binding} in new code, and to
> +convert existing Emacs Lisp code to use lexical binding if it doesn't
> +already.  @xref{Using Lexical Binding}.

There's a minor risk of confusion where this could be taken to mean that
we recommend code should be rewritten not to use any dynamically scoped
variables at all.

I'm not sure what would be the best wording to avoid this confusion.  Maybe:

    @item
    We recommended to enable @code{lexical-binding} in all new code, and
    to convert existing Emacs Lisp code to enable @code{lexical-binding}
    if it doesn't already.  @xref{Using Lexical Binding}.


-- Stefan




^ permalink raw reply	[flat|nested] 9+ messages in thread

* RE: Recommend lexical-binding in Coding Conventions
  2020-10-21 13:33 ` Stefan Monnier
@ 2020-10-21 14:52   ` Drew Adams
  2020-10-21 15:14     ` Stefan Kangas
  0 siblings, 1 reply; 9+ messages in thread
From: Drew Adams @ 2020-10-21 14:52 UTC (permalink / raw)
  To: Stefan Monnier, Stefan Kangas; +Cc: emacs-devel

> There's a minor risk of confusion where this could be taken to mean that
> we recommend code should be rewritten not to use any dynamically scoped
> variables at all.
> 
> I'm not sure what would be the best wording to avoid this confusion.  Maybe:
> 
>     @item
>     We recommended to enable @code{lexical-binding} in all new code, and
>     to convert existing Emacs Lisp code to enable @code{lexical-binding}
>     if it doesn't already.  @xref{Using Lexical Binding}.

I think the risk is more than minor, and there is already
a fair amount of confusion out there about this.

My suggestion is to speak only in terms of the variable,
`lexical-binding'.  Recommending that people set it to
non-nil is, I think, exactly what we want.  If they do
that then everything is as desired.

That doesn't say anything about using lexical or dynamic
binding.  And it automatically entails making code that
uses non-nil DTRT: if you set it to non-nil then you
need to make whatever changes are needed for that.



^ permalink raw reply	[flat|nested] 9+ messages in thread

* RE: Recommend lexical-binding in Coding Conventions
  2020-10-21 14:52   ` Drew Adams
@ 2020-10-21 15:14     ` Stefan Kangas
  2020-10-21 15:30       ` Alan Mackenzie
  2020-10-21 16:38       ` Drew Adams
  0 siblings, 2 replies; 9+ messages in thread
From: Stefan Kangas @ 2020-10-21 15:14 UTC (permalink / raw)
  To: Drew Adams, Stefan Monnier; +Cc: emacs-devel

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

>>     @item
>>     We recommended to enable @code{lexical-binding} in all new code, and
>>     to convert existing Emacs Lisp code to enable @code{lexical-binding}
>>     if it doesn't already.  @xref{Using Lexical Binding}.

Yes, that is indeed more clear.  Thanks.

> My suggestion is to speak only in terms of the variable,
> `lexical-binding'.

That suggestion is satisfied by the above edited text, right?



^ permalink raw reply	[flat|nested] 9+ messages in thread

* Re: Recommend lexical-binding in Coding Conventions
  2020-10-21 15:14     ` Stefan Kangas
@ 2020-10-21 15:30       ` Alan Mackenzie
  2020-10-21 16:07         ` Robert Pluim
  2020-10-21 16:19         ` Stefan Kangas
  2020-10-21 16:38       ` Drew Adams
  1 sibling, 2 replies; 9+ messages in thread
From: Alan Mackenzie @ 2020-10-21 15:30 UTC (permalink / raw)
  To: Stefan Kangas; +Cc: Stefan Monnier, Drew Adams, emacs-devel

Hello, Stefan.

On Wed, Oct 21, 2020 at 08:14:46 -0700, Stefan Kangas wrote:
> Drew Adams <drew.adams@oracle.com> writes:

> >>     @item
> >>     We recommended to enable @code{lexical-binding} in all new code, and
> >>     to convert existing Emacs Lisp code to enable @code{lexical-binding}
> >>     if it doesn't already.  @xref{Using Lexical Binding}.

> Yes, that is indeed more clear.  Thanks.

> > My suggestion is to speak only in terms of the variable,
> > `lexical-binding'.

> That suggestion is satisfied by the above edited text, right?

Just a couple of comments on the English usage.

We recommended -> we recommend.  :-)

The verb "recommend" needs a direct object (or gerund).  That direct
object can either be the thing recommended, or the person to whom the
recommendation is being made.

So, correct forms of your statement would be either:

    We recommend YOU to enable ... and to convert .....

or

    We recommend ENABLING .... and CONVERTING ....

.  English isn't always an easy language.  ;-)

-- 
Alan Mackenzie (Nuremberg, Germany).



^ permalink raw reply	[flat|nested] 9+ messages in thread

* Re: Recommend lexical-binding in Coding Conventions
  2020-10-21 15:30       ` Alan Mackenzie
@ 2020-10-21 16:07         ` Robert Pluim
  2020-10-21 16:19         ` Stefan Kangas
  1 sibling, 0 replies; 9+ messages in thread
From: Robert Pluim @ 2020-10-21 16:07 UTC (permalink / raw)
  To: Alan Mackenzie; +Cc: Stefan Kangas, Stefan Monnier, Drew Adams, emacs-devel

>>>>> On Wed, 21 Oct 2020 15:30:06 +0000, Alan Mackenzie <acm@muc.de> said:

    Alan> The verb "recommend" needs a direct object (or gerund).  That direct
    Alan> object can either be the thing recommended, or the person to whom the
    Alan> recommendation is being made.

    Alan> So, correct forms of your statement would be either:

    Alan>     We recommend YOU to enable ... and to convert .....

Nitpicking your nitpick: "We recommend you enable" or even "We
recommend that you enable"
(as opposed to eg "we advise you to enable")

    Alan> or

    Alan>     We recommend ENABLING .... and CONVERTING ....

    Alan> .  English isn't always an easy language.  ;-)

"It shouldn't be like that, but it do" ;-)

Robert
-- 



^ permalink raw reply	[flat|nested] 9+ messages in thread

* Re: Recommend lexical-binding in Coding Conventions
  2020-10-21 15:30       ` Alan Mackenzie
  2020-10-21 16:07         ` Robert Pluim
@ 2020-10-21 16:19         ` Stefan Kangas
  1 sibling, 0 replies; 9+ messages in thread
From: Stefan Kangas @ 2020-10-21 16:19 UTC (permalink / raw)
  To: Alan Mackenzie; +Cc: Stefan Monnier, Drew Adams, emacs-devel

Hi Alan,

Alan Mackenzie <acm@muc.de> writes:

> We recommended -> we recommend.  :-)
>
> The verb "recommend" needs a direct object (or gerund).  That direct
> object can either be the thing recommended, or the person to whom the
> recommendation is being made.
>
> So, correct forms of your statement would be either:
>
>     We recommend YOU to enable ... and to convert .....
>
> or
>
>     We recommend ENABLING .... and CONVERTING ....
>
> .  English isn't always an easy language.  ;-)

This is very useful.  I'll fix these mistakes before pushing.

Thanks for taking the time to write out a detailed explanation.



^ permalink raw reply	[flat|nested] 9+ messages in thread

* RE: Recommend lexical-binding in Coding Conventions
  2020-10-21 15:14     ` Stefan Kangas
  2020-10-21 15:30       ` Alan Mackenzie
@ 2020-10-21 16:38       ` Drew Adams
  1 sibling, 0 replies; 9+ messages in thread
From: Drew Adams @ 2020-10-21 16:38 UTC (permalink / raw)
  To: Stefan Kangas, Stefan Monnier; +Cc: emacs-devel

> That suggestion is satisfied by the above edited text, right?

Yes, technically.  But some will read it without attention to the code font and the hyphen.

My suggestion is to use the word "variable" in
front of "lexical-binding".  Make it very clear.
Don't allow misinterpretation that it's about
using lexical binding.



^ permalink raw reply	[flat|nested] 9+ messages in thread

end of thread, other threads:[~2020-10-21 16:38 UTC | newest]

Thread overview: 9+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2020-10-21  1:05 Recommend lexical-binding in Coding Conventions Stefan Kangas
2020-10-21  4:32 ` Drew Adams
2020-10-21 13:33 ` Stefan Monnier
2020-10-21 14:52   ` Drew Adams
2020-10-21 15:14     ` Stefan Kangas
2020-10-21 15:30       ` Alan Mackenzie
2020-10-21 16:07         ` Robert Pluim
2020-10-21 16:19         ` Stefan Kangas
2020-10-21 16:38       ` Drew Adams

Code repositories for project(s) associated with this public inbox

	https://git.savannah.gnu.org/cgit/emacs.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).