GNU bug report logs - #50658
Error messages including function names violates coding conventions

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 50658 in the body.
You can then email your comments to 50658 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: Stefan Kangas <stefan <at> marxist.se>
To: bug-gnu-emacs <at> gnu.org
Subject: Error messages including function names violates coding conventions
Date: Sat, 18 Sep 2021 03:52:54 -0700

Severity: minor

We currently have a whole lot of places in Emacs where the error message
include the function name that they come from, such as:

    (error "ad-read-advised-function: There are no advised functions")

This violates our coding convention in `(elisp) Programming Tips':

   • An error message should start with a capital letter but should not
     end with a period.

These cases are all flagged by checkdoc when it tries to enforce the
above convention.

Fixing all these according to our current conventions would in the above
case mean that it should say:

   (error "There are no advised functions")

Unfortunately, this might lose some pertinent information (the function
name) if the user is running with `debug-on-error' off.

Do we care about that?  If we don't care, we should just make the above
change, and there is nothing more to discuss.

If we do care, I see three options:

1. We decide on some format for how to type out the function name that
   does not put it at the start of the message (since that violates the
   coding convention), and then we document that to be the convention.

2. We modify the above coding convention to say that including the
   function name at the start is okay.  Presumably this includes
   updating checkdoc to check that it is actually the function name that
   is used (or perhaps to just accept any symbol).

3. We add some way of displaying the function name in the error message
   without having to type it out.

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Stefan Kangas <stefan <at> marxist.se>
Cc: 50658 <at> debbugs.gnu.org
Subject: Re: bug#50658: Error messages including function names violates coding
 conventions
Date: Sat, 18 Sep 2021 14:08:38 +0300

> From: Stefan Kangas <stefan <at> marxist.se>
> Date: Sat, 18 Sep 2021 03:52:54 -0700
> 
> We currently have a whole lot of places in Emacs where the error message
> include the function name that they come from, such as:
> 
>     (error "ad-read-advised-function: There are no advised functions")
> 
> This violates our coding convention in `(elisp) Programming Tips':
> 
>    • An error message should start with a capital letter but should not
>      end with a period.
> 
> These cases are all flagged by checkdoc when it tries to enforce the
> above convention.

I think it's a bug in checkdoc: the error message text, which excludes
the function name, fulfills the requirement.

> If we do care, I see three options:
> 
> 1. We decide on some format for how to type out the function name that
>    does not put it at the start of the message (since that violates the
>    coding convention), and then we document that to be the convention.
> 
> 2. We modify the above coding convention to say that including the
>    function name at the start is okay.  Presumably this includes
>    updating checkdoc to check that it is actually the function name that
>    is used (or perhaps to just accept any symbol).
> 
> 3. We add some way of displaying the function name in the error message
>    without having to type it out.

I think 2 is TRT, except that it isn't really a change in the
conventions.

Thanks.

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

From: Stefan Kangas <stefan <at> marxist.se>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 50658 <at> debbugs.gnu.org
Subject: Re: bug#50658: Error messages including function names violates
 coding conventions
Date: Sat, 18 Sep 2021 04:58:01 -0700

Eli Zaretskii <eliz <at> gnu.org> writes:

> I think it's a bug in checkdoc: the error message text, which excludes
> the function name, fulfills the requirement.

OK, I'll see about fixing it.

>> 2. We modify the above coding convention to say that including the
>>    function name at the start is okay.  Presumably this includes
>>    updating checkdoc to check that it is actually the function name that
>>    is used (or perhaps to just accept any symbol).
>
> I think 2 is TRT, except that it isn't really a change in the
> conventions.

How about this clarification:

diff --git a/doc/lispref/tips.texi b/doc/lispref/tips.texi
index a72ab88cef..c6c16211e4 100644
--- a/doc/lispref/tips.texi
+++ b/doc/lispref/tips.texi
@@ -392,8 +392,9 @@ Programming Tips
 @code{beep} to report errors.

 @item
-An error message should start with a capital letter but should not end
-with a period.
+An error message should start with a capital letter or a Lisp symbol,
+as in ``foo-command: Invalid input''.  It should not end with a
+period.

 @item
 A question asked in the minibuffer with @code{yes-or-no-p} or

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Stefan Kangas <stefan <at> marxist.se>
Cc: 50658 <at> debbugs.gnu.org
Subject: Re: bug#50658: Error messages including function names violates
 coding conventions
Date: Sat, 18 Sep 2021 15:02:54 +0300

> From: Stefan Kangas <stefan <at> marxist.se>
> Date: Sat, 18 Sep 2021 04:58:01 -0700
> Cc: 50658 <at> debbugs.gnu.org
> 
> >> 2. We modify the above coding convention to say that including the
> >>    function name at the start is okay.  Presumably this includes
> >>    updating checkdoc to check that it is actually the function name that
> >>    is used (or perhaps to just accept any symbol).
> >
> > I think 2 is TRT, except that it isn't really a change in the
> > conventions.
> 
> How about this clarification:
> 
> diff --git a/doc/lispref/tips.texi b/doc/lispref/tips.texi
> index a72ab88cef..c6c16211e4 100644
> --- a/doc/lispref/tips.texi
> +++ b/doc/lispref/tips.texi
> @@ -392,8 +392,9 @@ Programming Tips
>  @code{beep} to report errors.
> 
>  @item
> -An error message should start with a capital letter but should not end
> -with a period.
> +An error message should start with a capital letter or a Lisp symbol,
> +as in ``foo-command: Invalid input''.  It should not end with a
> +period.

Thanks.  If we are going to show examples (which is a good idea, IMO),
I think we should show both examples with and without the function
name, and therefore some wording about the function name being
optional, and that the rule is not applicable to it, is in order.

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

From: Stefan Kangas <stefan <at> marxist.se>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 50658 <at> debbugs.gnu.org
Subject: Re: bug#50658: Error messages including function names violates
 coding conventions
Date: Sat, 18 Sep 2021 05:49:37 -0700

Eli Zaretskii <eliz <at> gnu.org> writes:

> Thanks.  If we are going to show examples (which is a good idea, IMO),
> I think we should show both examples with and without the function
> name, and therefore some wording about the function name being
> optional, and that the rule is not applicable to it, is in order.

OK, that makes sense.  What do you think of this:

diff --git a/doc/lispref/tips.texi b/doc/lispref/tips.texi
index a72ab88cef..77947837b7 100644
--- a/doc/lispref/tips.texi
+++ b/doc/lispref/tips.texi
@@ -393,7 +393,11 @@ Programming Tips

 @item
 An error message should start with a capital letter but should not end
-with a period.
+with a period or other punctuation.  It sometimes makes sense to
+include a Lisp symbol in the error message, in cases where it is
+useful for a user to know where the error originated.  For example,
+the error message ``Invalid input'' could be extended to say
+``some-command: Invalid input''.

 @item
 A question asked in the minibuffer with @code{yes-or-no-p} or

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Stefan Kangas <stefan <at> marxist.se>
Cc: 50658 <at> debbugs.gnu.org
Subject: Re: bug#50658: Error messages including function names violates
 coding conventions
Date: Sat, 18 Sep 2021 16:25:32 +0300

> From: Stefan Kangas <stefan <at> marxist.se>
> Date: Sat, 18 Sep 2021 05:49:37 -0700
> Cc: 50658 <at> debbugs.gnu.org
> 
> Eli Zaretskii <eliz <at> gnu.org> writes:
> 
> > Thanks.  If we are going to show examples (which is a good idea, IMO),
> > I think we should show both examples with and without the function
> > name, and therefore some wording about the function name being
> > optional, and that the rule is not applicable to it, is in order.
> 
> OK, that makes sense.  What do you think of this:

LGTM, thanks.

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

From: Stefan Kangas <stefan <at> marxist.se>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 50658 <at> debbugs.gnu.org
Subject: Re: bug#50658: Error messages including function names violates
 coding conventions
Date: Sat, 18 Sep 2021 07:54:26 -0700

Eli Zaretskii <eliz <at> gnu.org> writes:

>>    • An error message should start with a capital letter but should not
>>      end with a period.
>>
>> These cases are all flagged by checkdoc when it tries to enforce the
>> above convention.
>
> I think it's a bug in checkdoc: the error message text, which excludes
> the function name, fulfills the requirement.

While working on this, I realized that it is impossible to know if in
something like:

    (error "frobnicator not available")

The 'frobnicator' part is a Lisp symbol (that can be in lower-case), or
if it is a regular word (that must be capitalized).  It would obviously
be helpful if our conventions could be unambiguous.

Perhaps we could add a requirement here, something like: a Lisp symbol
must always be in `quotes', or behind ": "?

(I guess this would also affect the text we want to put in `(elisp)
Documentation Tips'.)

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Stefan Kangas <stefan <at> marxist.se>
Cc: 50658 <at> debbugs.gnu.org
Subject: Re: bug#50658: Error messages including function names violates
 coding conventions
Date: Sat, 18 Sep 2021 18:00:00 +0300

> From: Stefan Kangas <stefan <at> marxist.se>
> Date: Sat, 18 Sep 2021 07:54:26 -0700
> Cc: 50658 <at> debbugs.gnu.org
> 
> While working on this, I realized that it is impossible to know if in
> something like:
> 
>     (error "frobnicator not available")
> 
> The 'frobnicator' part is a Lisp symbol (that can be in lower-case), or
> if it is a regular word (that must be capitalized).  It would obviously
> be helpful if our conventions could be unambiguous.
> 
> Perhaps we could add a requirement here, something like: a Lisp symbol
> must always be in `quotes', or behind ": "?

Yes, I think the idea is that the error message proper starts after
the colon.

> (I guess this would also affect the text we want to put in `(elisp)
> Documentation Tips'.)

Yes.

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

From: Stefan Kangas <stefan <at> marxist.se>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 50658 <at> debbugs.gnu.org
Subject: Re: bug#50658: Error messages including function names violates
 coding conventions
Date: Mon, 27 Sep 2021 16:25:09 -0700

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

Eli Zaretskii <eliz <at> gnu.org> writes:

>> Perhaps we could add a requirement here, something like: a Lisp symbol
>> must always be in `quotes', or behind ": "?
>
> Yes, I think the idea is that the error message proper starts after
> the colon.
>
>> (I guess this would also affect the text we want to put in `(elisp)
>> Documentation Tips'.)
>
> Yes.

Please find attached a patch.  WDYT?  Too wordy?

[0001-Improve-coding-conventions-for-error-messages.patch (text/x-diff, attachment)]

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Stefan Kangas <stefan <at> marxist.se>
Cc: 50658 <at> debbugs.gnu.org
Subject: Re: bug#50658: Error messages including function names violates
 coding conventions
Date: Tue, 28 Sep 2021 08:54:52 +0300

> From: Stefan Kangas <stefan <at> marxist.se>
> Date: Mon, 27 Sep 2021 16:25:09 -0700
> Cc: 50658 <at> debbugs.gnu.org
> 
> >> (I guess this would also affect the text we want to put in `(elisp)
> >> Documentation Tips'.)
> >
> > Yes.
> 
> Please find attached a patch.  WDYT?  Too wordy?

No, it's okay.  A few minor nits, though:

> +It is occasionally useful to tell the user where an error originated,
> +even if @code{debug-on-error} is nil.  In such cases, a lower-case
> +Lisp symbol can be added to the error message.  For example, the error
                      ^^^^^
"prepended" is better here.

> +message ``Invalid input'' could be extended say ``some-function:
                                               ^^^
"to say"

> +Invalid input''.  This convention is better avoided in most cases.

That last sentence is unexpected, and seems to contradict everything
you wrote before it.  Which convention should be avoided, and why?

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

From: Stefan Kangas <stefan <at> marxist.se>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 50658 <at> debbugs.gnu.org
Subject: Re: bug#50658: Error messages including function names violates
 coding conventions
Date: Tue, 28 Sep 2021 05:11:23 -0700

Eli Zaretskii <eliz <at> gnu.org> writes:

>> +Invalid input''.  This convention is better avoided in most cases.
>
> That last sentence is unexpected, and seems to contradict everything
> you wrote before it.  Which convention should be avoided, and why?

To be honest, I was a bit unsure about this sentence.  I guess I'm
trying to say "don't overdo it" or "don't do it by default just because
you can".

But perhaps this is already clear from the rest of the text?

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Stefan Kangas <stefan <at> marxist.se>
Cc: 50658 <at> debbugs.gnu.org
Subject: Re: bug#50658: Error messages including function names violates
 coding conventions
Date: Tue, 28 Sep 2021 15:28:59 +0300

> From: Stefan Kangas <stefan <at> marxist.se>
> Date: Tue, 28 Sep 2021 05:11:23 -0700
> Cc: 50658 <at> debbugs.gnu.org
> 
> Eli Zaretskii <eliz <at> gnu.org> writes:
> 
> >> +Invalid input''.  This convention is better avoided in most cases.
> >
> > That last sentence is unexpected, and seems to contradict everything
> > you wrote before it.  Which convention should be avoided, and why?
> 
> To be honest, I was a bit unsure about this sentence.  I guess I'm
> trying to say "don't overdo it" or "don't do it by default just because
> you can".
> 
> But perhaps this is already clear from the rest of the text?

Yes, I think it is.

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

From: Stefan Kangas <stefan <at> marxist.se>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 50658 <at> debbugs.gnu.org
Subject: Re: bug#50658: Error messages including function names violates
 coding conventions
Date: Tue, 28 Sep 2021 05:59:20 -0700

tags 50658 fixed
close 50658 28.1
thanks

Eli Zaretskii <eliz <at> gnu.org> writes:

>> But perhaps this is already clear from the rest of the text?
>
> Yes, I think it is.

OK, I deleted that sentence and pushed the rest with your fixes to
master (commit e9c7ef3348).  I'm therefore closing this bug report.

Previous Next

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