CodingGuidelines: a handful of error message guidelines
It is more efficient to have something in the coding guidelines document to point at, when we want to review and comment on a new message in the codebase to make sure it "fits" in the set of existing messages. Let's write down established best practice we are aware of. Helped-by: Eric Sunshine <sunshine@sunshineco.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Junio C Hamano committed
Nov 27, 2024 at 22:23 UTC
168ebb7159584df425797dd13d8d8986dc08051e
1 file changed
+17
-3
Documentation/CodingGuidelines
+17
-3
@@ -689,16 +689,30 @@ Program Output
689
690
Error Messages
691
692
- - Do not end error messages with a full stop.
692
+ - Do not end a single-sentence error message with a full stop.
693
694
- Do not capitalize the first word, only because it is the first word
695
- in the message ("unable to open %s", not "Unable to open %s"). But
695
+ in the message ("unable to open '%s'", not "Unable to open '%s'"). But
696
"SHA-3 not supported" is fine, because the reason the first word is
697
capitalized is not because it is at the beginning of the sentence,
698
but because the word would be spelled in capital letters even when
699
it appeared in the middle of the sentence.
700
701
- - Say what the error is first ("cannot open %s", not "%s: cannot open")
701
+ - Say what the error is first ("cannot open '%s'", not "%s: cannot open").
702
+
703
+ - Enclose the subject of an error inside a pair of single quotes,
704
+ e.g. `die(_("unable to open '%s'"), path)`.
705
+
706
+ - Unless there is a compelling reason not to, error messages from
707
+ porcelain commands should be marked for translation, e.g.
708
+ `die(_("bad revision %s"), revision)`.
709
+
710
+ - Error messages from the plumbing commands are sometimes meant for
711
+ machine consumption and should not be marked for translation,
712
+ e.g., `die("bad revision %s", revision)`.
713
+
714
+ - BUG("message") are for communicating the specific error to developers,
715
+ thus should not be translated.
716
717
718
Externally Visible Names