From f3a44d773c601c9b708215e0590a806ca897d441 Mon Sep 17 00:00:00 2001
From: "Chao Li (Evan)" <lic@highgo.com>
Date: Tue, 17 Mar 2026 10:47:08 +0800
Subject: [PATCH v1] elog: document style guidelines for error message
 functions

Add brief style guidelines to the header comments of errmsg(),
errdetail(), errhint(), errcontext() and elog.

The styles are described in:

* https://www.postgresql.org/docs/current/error-style-guide.html
* https://www.postgresql.org/docs/devel/error-message-reporting.html

Author: Chao Li <lic@highgo.com>
---
 src/backend/utils/error/elog.c | 13 +++++++++++++
 src/include/utils/elog.h       |  8 ++++++++
 2 files changed, 21 insertions(+)

diff --git a/src/backend/utils/error/elog.c b/src/backend/utils/error/elog.c
index 80b78f25267..f4ffb9c3f50 100644
--- a/src/backend/utils/error/elog.c
+++ b/src/backend/utils/error/elog.c
@@ -1086,6 +1086,9 @@ errcode_for_socket_access(void)
  * In addition to the usual %-escapes recognized by printf, "%m" in
  * fmt is replaced by the error message for the caller's value of errno.
  *
+ * Style guidelines: do not capitalize the first letter, and do not end
+ * the message with a period or other punctuation.
+ *
  * Note: no newline is needed at the end of the fmt string, since
  * ereport will provide one for the output methods that need it.
  */
@@ -1389,6 +1392,11 @@ errmsg_plural(const char *fmt_singular, const char *fmt_plural,
 
 /*
  * errdetail --- add a detail error message text to the current error
+ *
+ * Style guidelines: use complete sentences; capitalize the first word
+ * of each sentence, and end each with a period; put two spaces after
+ * a period if another sentence follows (for English text; may be
+ * inappropriate in other languages).
  */
 int
 errdetail(const char *fmt,...)
@@ -1503,6 +1511,11 @@ errdetail_plural(const char *fmt_singular, const char *fmt_plural,
 
 /*
  * errhint --- add a hint error message text to the current error
+ *
+ * Style guidelines: use complete sentences; capitalize the first word
+ * of each sentence, and end each with a period; put two spaces after
+ * a period if another sentence follows (for English text; may be
+ * inappropriate in other languages).
  */
 int
 errhint(const char *fmt,...)
diff --git a/src/include/utils/elog.h b/src/include/utils/elog.h
index a12b379e09a..b45ef9165b9 100644
--- a/src/include/utils/elog.h
+++ b/src/include/utils/elog.h
@@ -208,6 +208,9 @@ extern int	errhint_plural(const char *fmt_singular, const char *fmt_plural,
  * is not usually the correct domain for translating the context message.
  * set_errcontext_domain() first sets the domain to be used, and
  * errcontext_msg() passes the actual message.
+ *
+ * Style guidelines: do not capitalize the first letter, do not end the string
+ * with a period, and avoid complete sentences.
  */
 #define errcontext	set_errcontext_domain(TEXTDOMAIN),	errcontext_msg
 
@@ -235,6 +238,11 @@ extern int	getinternalerrposition(void);
 /*----------
  * Old-style error reporting API: to be used in this way:
  *		elog(ERROR, "portal \"%s\" not found", stmt->portalname);
+ *
+ * elog() is intended for internal errors and low-level debug logging.
+ * It always uses a default SQLSTATE, and the message is not translated.
+ * Messages that may be of interest to end users should use ereport()
+ * instead.
  *----------
  */
 #define elog(elevel, ...)  \
-- 
2.50.1 (Apple Git-155)