bug#50658: Error messages including function names violates coding conventions

bug#50658: Error messages including function names violates coding conventions

[Stefan Kangas]

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.

bug#50658: Error messages including function names violates coding conventions

[Eli Zaretskii]

> From: Stefan Kangas <stefan@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.

bug#50658: Error messages including function names violates coding conventions

[Stefan Kangas]

Eli Zaretskii <eliz@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

bug#50658: Error messages including function names violates coding conventions

[Eli Zaretskii]

> From: Stefan Kangas <stefan@marxist.se>
> Date: Sat, 18 Sep 2021 04:58:01 -0700
> Cc: 50658@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.

bug#50658: Error messages including function names violates coding conventions

[Stefan Kangas]

Eli Zaretskii <eliz@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

bug#50658: Error messages including function names violates coding conventions

[Eli Zaretskii]

> From: Stefan Kangas <stefan@marxist.se>
> Date: Sat, 18 Sep 2021 05:49:37 -0700
> Cc: 50658@debbugs.gnu.org
> 
> Eli Zaretskii <eliz@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.

bug#50658: Error messages including function names violates coding conventions

[Stefan Kangas]

Eli Zaretskii <eliz@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'.)

bug#50658: Error messages including function names violates coding conventions

[Eli Zaretskii]

> From: Stefan Kangas <stefan@marxist.se>
> Date: Sat, 18 Sep 2021 07:54:26 -0700
> Cc: 50658@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.

bug#50658: Error messages including function names violates coding conventions

[Stefan Kangas]

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

Eli Zaretskii <eliz@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?

[-- Attachment #2: 0001-Improve-coding-conventions-for-error-messages.patch --]
[-- Type: text/x-diff, Size: 1218 bytes --]

From 522ff5074033208da5470ea418bc27777cfcc220 Mon Sep 17 00:00:00 2001
From: Stefan Kangas <stefan@marxist.se>
Date: Mon, 27 Sep 2021 23:34:36 +0200
Subject: [PATCH] Improve coding conventions for error messages

* doc/lispref/tips.texi (Programming Tips): Clarify coding
conventions for error messages to say that an error message can
start with a Lisp symbol.  (Bug#50658)
---
 doc/lispref/tips.texi | 8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)

diff --git a/doc/lispref/tips.texi b/doc/lispref/tips.texi
index e56ddf3c28..2eb6c78212 100644
--- a/doc/lispref/tips.texi
+++ b/doc/lispref/tips.texi
@@ -393,7 +393,13 @@ 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 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
+message ``Invalid input'' could be extended say ``some-function:
+Invalid input''.  This convention is better avoided in most cases.
 
 @item
 A question asked in the minibuffer with @code{yes-or-no-p} or
-- 
2.30.2

bug#50658: Error messages including function names violates coding conventions

[Eli Zaretskii]

> From: Stefan Kangas <stefan@marxist.se>
> Date: Mon, 27 Sep 2021 16:25:09 -0700
> Cc: 50658@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?

bug#50658: Error messages including function names violates coding conventions

[Stefan Kangas]

Eli Zaretskii <eliz@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?

bug#50658: Error messages including function names violates coding conventions

[Eli Zaretskii]

> From: Stefan Kangas <stefan@marxist.se>
> Date: Tue, 28 Sep 2021 05:11:23 -0700
> Cc: 50658@debbugs.gnu.org
> 
> Eli Zaretskii <eliz@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.

bug#50658: Error messages including function names violates coding conventions

[Stefan Kangas]

tags 50658 fixed
close 50658 28.1
thanks

Eli Zaretskii <eliz@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.