adding to emacs coding standard / formatting

adding to emacs coding standard / formatting

[Boruch Baum]

My work apropos the thread " ~Make emacs friendlier: package documentation [POC
CODE INCLUDED]" highlighted to me benefit to proposing to add to the
accepted / suggested / required format of emacs elisp packages.

I had expecting symbol definitions to be grouped together by symbol type
and function, eg. all `defcustom's to be listed together in a section
beginning "^;;; Customization variables:", and so on for symbol
categories ";;; Global variables:", ";;; Buffer-local variables", ";;;
Internal functions:", ";;; Hook functions:", ";;; Interactive
functions:", etc.

That isn't the case in package time.el, so that's probably also the case
in other packages. Should doing so be added to the coding standard?

Also, this is an opportunity to address a pet peeve: I occasionally see
code either defining keybindings to lambda functions, or setting lambda
functions as elements of function lists (eg. lists of hook functions).
I'd like to propose that those uses be banned because of their
difficulty to modify.

--
hkp://keys.gnupg.net
CA45 09B5 5351 7C11 A9D1  7286 0036 9E45 1595 8BC0

Re: adding to emacs coding standard / formatting

[Stefan Kangas]

Boruch Baum <boruch_baum@gmx.com> writes:

> My work apropos the thread " ~Make emacs friendlier: package documentation [POC
> CODE INCLUDED]" highlighted to me benefit to proposing to add to the
> accepted / suggested / required format of emacs elisp packages.
>
> I had expecting symbol definitions to be grouped together by symbol type
> and function, eg. all `defcustom's to be listed together in a section
> beginning "^;;; Customization variables:", and so on for symbol
> categories ";;; Global variables:", ";;; Buffer-local variables", ";;;
> Internal functions:", ";;; Hook functions:", ";;; Interactive
> functions:", etc.
>
> That isn't the case in package time.el, so that's probably also the case
> in other packages. Should doing so be added to the coding standard?

FWIW, I wouldn't like to see this added to our coding standards at a
language level.  I find it overly bureaucratic.  Files should follow a
standard that makes sense to what its trying to present.

Also, third-party package developers should have some room to maintain
their own standards.

(That said, I'm not a fan of the organization in time.el, as it mixes
unrelated things in one file and violates our prefix naming
conventions.)

RE: adding to emacs coding standard / formatting

[Drew Adams]

> FWIW, I wouldn't like to see this added to our coding standards at a
> language level.  I find it overly bureaucratic.  Files should follow a
> standard that makes sense to what its trying to present.
> 
> Also, third-party package developers should have some room to maintain
> their own standards.

FWIW, I agree.

I personally do group things, and label the groupings,
when it makes sense.

But there are different ways to group/organize things,
and, as always, local consistency is more important
than global consistency.  (Who knows best which
organization makes most sense locally?  The author.)

For example, it may typically make sense to put
defcustoms together - I generally do that, in a
section labeled to that effect.

But sometimes it makes sense to put a particular
defcustom together with some other bits of code
directly related to it, where that group of stuff is
not so tightly related to the other parts of the file.
For example, when some subfeature is involved, guarded
by some condition, e.g., (when (featurep 'foo) ...).

Our coding conventions are just guidelines (except
for inclusion in Emacs, where they're considered more
strictly).  But they should be important, not
gratuitous.  In general, users should be the judges of
how to organize and present their work.  Guidelines
should be a help, not a hindrance.

[BTW, there is plenty of code that's part of Emacs
that doesn't strictly follow our guidelines - max
line length, for instance.]

Re: adding to emacs coding standard / formatting

[Stefan Monnier]

> That isn't the case in package time.el, so that's probably also the case
> in other packages.  Should doing so be added to the coding standard?

While this can work well for some files, I think it would work poorly
for others, so I'd rather not require this specific standard (and
I expect it will be difficult to get enough agreement on any specific
proposal anyway).

But I'd be in favor of encouraging such structure, e.g. by "leading by
example", or by having `C-h P` give better result for packages which do
follow such a structure, or by providing good templates (hooked into
the auto-insert system), ...

Maybe we can also mention the importance of such a structure *in
general*, without recommending any one particular structure  but just
showing a few good examples.

> Also, this is an opportunity to address a pet peeve: I occasionally see
> code either defining keybindings to lambda functions, or setting lambda
> functions as elements of function lists (eg. lists of hook functions).
> I'd like to propose that those uses be banned because of their
> difficulty to modify.

I think I mostly agree, but as always there will be exceptions where
using a symbol is impossible or wouldn't help (typically because the
function really can't be predefined once and for all).

Maybe you could start by adding compiler warnings for those, and then
submit patches that address the easy-to-fix cases.


        Stefan

Re: adding to emacs coding standard / formatting

[Eli Zaretskii]

> Date: Sun, 18 Oct 2020 23:10:02 -0400
> From: Boruch Baum <boruch_baum@gmx.com>
> 
> I had expecting symbol definitions to be grouped together by symbol type
> and function, eg. all `defcustom's to be listed together in a section
> beginning "^;;; Customization variables:", and so on for symbol
> categories ";;; Global variables:", ";;; Buffer-local variables", ";;;
> Internal functions:", ";;; Hook functions:", ";;; Interactive
> functions:", etc.

Many packages group together defcustoms, variables, and functions that
belong to a logical sub-group of features (and  normally indicate such
a group with a ^L character).  I don't see why we should disallow such
organization, it is useful to have related stuff close.

> Also, this is an opportunity to address a pet peeve: I occasionally see
> code either defining keybindings to lambda functions, or setting lambda
> functions as elements of function lists (eg. lists of hook functions).
> I'd like to propose that those uses be banned because of their
> difficulty to modify.

Where would you allow lambda functions, then?

Re: adding to emacs coding standard / formatting

[Boruch Baum]

On 2020-10-19 17:32, Eli Zaretskii wrote:
> > Date: Sun, 18 Oct 2020 23:10:02 -0400
> >
> > Also, this is an opportunity to address a pet peeve: I occasionally see
> > code either defining keybindings to lambda functions, or setting lambda
> > functions as elements of function lists (eg. lists of hook functions).
> > I'd like to propose that those uses be banned because of their
> > difficulty to modify.
>
> Where would you allow lambda functions, then?

I see them most used as arguments/predicates to mapping functions or as
common-lisp predicates (eg. :test).

My complaint is against their use in situations that make standard
manipulation practices difficult: 1) When you assign a keybinding to a
lambda function, you can't remap to it; 2) When you add a lambda
function to a list, you lose the ability to perform operations such as
memq, delq, and you can't modify the element in place.

--
hkp://keys.gnupg.net
CA45 09B5 5351 7C11 A9D1  7286 0036 9E45 1595 8BC0

RE: adding to emacs coding standard / formatting

[Drew Adams]

> > > Also, this is an opportunity to address a pet peeve: I occasionally see
> > > code either defining keybindings to lambda functions, or setting lambda
> > > functions as elements of function lists (eg. lists of hook functions).
> > > I'd like to propose that those uses be banned because of their
> > > difficulty to modify.
> >
> > Where would you allow lambda functions, then?
> 
> I see them most used as arguments/predicates to mapping functions or as
> common-lisp predicates (eg. :test).
> 
> My complaint is against their use in situations that make standard
> manipulation practices difficult: 1) When you assign a keybinding to a
> lambda function, you can't remap to it; 2) When you add a lambda
> function to a list, you lose the ability to perform operations such as
> memq, delq, and you can't modify the element in place.

Why would this be part of the code conventions?

Yes, users should be given this guidance, to save
themselves trouble (e.g. for advice and hooks).
And they should be told the reasons (i.e., told
about the potential bother).  I agree with that
whole-heartedly.

But what does this have to do with coding
conventions?  (Let alone why would such usage be
"banned".)

This is on the order of helpful tips, not coding
conventions, IMO.

Re: adding to emacs coding standard / formatting

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

  > But what does this have to do with coding
  > conventions?  (Let alone why would such usage be
  > "banned".)

  > This is on the order of helpful tips, not coding
  > conventions, IMO.

For users, it should be a tip.
However, we might want to insist on this for code in Emacs, GNU ELPA
or NonGNU ELPA when we have that.


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

RE: adding to emacs coding standard / formatting

[Drew Adams]

>   > But what does this have to do with coding
>   > conventions?  (Let alone why would such usage be
>   > "banned".)
> 
>   > This is on the order of helpful tips, not coding
>   > conventions, IMO.
> 
> For users, it should be a tip.
> However, we might want to insist on this for code in Emacs, GNU ELPA
> or NonGNU ELPA when we have that.

Yes, that was my thought exactly.  Thanks for stating
it plainly.

The coding conventions in the manual serve a double
purpose.  Things mentioned there are (1) pretty much
mandatory for inclusion in Emacs and (2) recommendations
for other Elisp code (e.g. user/3rd-party).

Re: adding to emacs coding standard / formatting

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

  > I had expecting symbol definitions to be grouped together by symbol type
  > and function, eg. all `defcustom's to be listed together in a section
  > beginning "^;;; Customization variables:", and so on for symbol
  > categories ";;; Global variables:", ";;; Buffer-local variables", ";;;
  > Internal functions:", ";;; Hook functions:", ";;; Interactive
  > functions:", etc.

The reason Lisp files are not always organized that way is that other
ways of organizing them sometimes make more sense.  For instance, to
put a variable definition next to the functions that it relates to.
To put internal functions next to the entry points that call them.


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

Re: adding to emacs coding standard / formatting

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

  > Also, this is an opportunity to address a pet peeve: I occasionally see
  > code either defining keybindings to lambda functions, or setting lambda
  > functions as elements of function lists (eg. lists of hook functions).
  > I'd like to propose that those uses be banned because of their
  > difficulty to modify.

I think we recommend not doing that.  Maybe we should say this also in
tips.texi.  Want to propose a patch?

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

Re: adding to emacs coding standard / formatting

[Boruch Baum]

On 2020-10-20 01:11, Richard Stallman wrote:
> [[[ 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. ]]]
>
>   > Also, this is an opportunity to address a pet peeve: I occasionally see
>   > code either defining keybindings to lambda functions, or setting lambda
>   > functions as elements of function lists (eg. lists of hook functions).
>   > I'd like to propose that those uses be banned because of their
>   > difficulty to modify.
>
> I think we recommend not doing that.  Maybe we should say this also in
> tips.texi.  Want to propose a patch?

For all the many years I've been using emacs and coding in elisp, I have
no idea what tips.texi is or how to access it! I guess that speaks to
another subject discussed on this list: the fragmentation and abundance
of emacs help resources?

--
hkp://keys.gnupg.net
CA45 09B5 5351 7C11 A9D1  7286 0036 9E45 1595 8BC0

Re: adding to emacs coding standard / formatting

[Eli Zaretskii]

On October 20, 2020 8:55:48 AM GMT+03:00, Boruch Baum <boruch_baum@gmx.com> wrote:
> On 2020-10-20 01:11, Richard Stallman wrote:
> > [[[ 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.
> ]]]
> >
> >   > Also, this is an opportunity to address a pet peeve: I
> occasionally see
> >   > code either defining keybindings to lambda functions, or setting
> lambda
> >   > functions as elements of function lists (eg. lists of hook
> functions).
> >   > I'd like to propose that those uses be banned because of their
> >   > difficulty to modify.
> >
> > I think we recommend not doing that.  Maybe we should say this also
> in
> > tips.texi.  Want to propose a patch?
> 
> For all the many years I've been using emacs and coding in elisp, I
> have
> no idea what tips.texi is or how to access it! I guess that speaks to
> another subject discussed on this list: the fragmentation and
> abundance
> of emacs help resources?

It's an appendix in the ELisp manual.  Type "g Tips RET".

Re: adding to emacs coding standard / formatting

[Jean Louis]

* Boruch Baum <boruch_baum@gmx.com> [2020-10-20 09:18]:
> On 2020-10-20 01:11, Richard Stallman wrote:
> > [[[ 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. ]]]
> >
> >   > Also, this is an opportunity to address a pet peeve: I occasionally see
> >   > code either defining keybindings to lambda functions, or setting lambda
> >   > functions as elements of function lists (eg. lists of hook functions).
> >   > I'd like to propose that those uses be banned because of their
> >   > difficulty to modify.
> >
> > I think we recommend not doing that.  Maybe we should say this also in
> > tips.texi.  Want to propose a patch?
> 
> For all the many years I've been using emacs and coding in elisp, I have
> no idea what tips.texi is or how to access it! I guess that speaks to
> another subject discussed on this list: the fragmentation and abundance
> of emacs help resources?

I guess texinfo file forms this section of Emacs Lisp manual, it is
then in that manual.

Tips and Conventions

* Coding Conventions::      Conventions for clean and robust programs.
* Key Binding Conventions:: Which keys should be bound by which programs.
* Programming Tips::        Making Emacs code fit smoothly in Emacs.
* Compilation Tips::        Making compiled code run fast.
* Warning Tips::            Turning off compiler warnings.
* Documentation Tips::      Writing readable documentation strings.
* Comment Tips::            Conventions for writing comments.
* Library Headers::         Standard headers for library packages.