From f3a44d773c601c9b708215e0590a806ca897d441 Mon Sep 17 00:00:00 2001 From: "Chao Li (Evan)" 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 --- 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)