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

[Stefan Kangas <stefan@marxist.se>]

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