Re: [PATCH v2 3/3] Capitalization and punctuation fixes to some user visible messages

From: Junio C Hamano <gitster@pobox.com>
Date: Apr 28, 2023, 19:09 UTC
Message-ID: <xmqq7ctvddsb.fsf@gitster.g>
In-Reply-To: <xmqqttwzded6.fsf@gitster.g>

Junio C Hamano <gitster@pobox.com> writes:

Show 15 quoted lines

> Oswald Buddenhagen <oswald.buddenhagen@gmx.de> writes:
>
>> These are conscious violations of the usual rules for error messages,
>> based on this reasoning:
>> - If an error message is directly followed by another sentence, it needs
>>   to be properly terminated with a period, lest the grammar looks broken
>>   and becomes hard to read.
>> - That second sentence isn't actually an error message any more, so it
>>   should abide to conventional language rules for good looks and
>>   legibility. Arguably, these should be converted to advice messages
>>   (which the user can squelch, too), but that's a much bigger effort to
>>   get right.
>
> I think both of the above are good guidelines to follow, with a hint
> for a longer-term plan.  Good description.

I think the above two deserves to be added (in some rephrased form to fit better) to the Documentation/CodingGuidelines, somewhere in the following section:

--- >8 --- Error Messages

 - Do not end error messages with a full stop.

 - Do not capitalize the first word, only because it is the first word
   in the message ("unable to open %s", not "Unable to open %s").  But
   "SHA-3 not supported" is fine, because the reason the first word is
   capitalized is not because it is at the beginning of the sentence,
   but because the word would be spelled in capital letters even when
   it appeared in the middle of the sentence.

 - Say what the error is first ("cannot open %s", not "%s: cannot open")

--- 8< ---

Volunteers?

Thanks.