Re: [PATCH] doc: State coding guideline for error message punctuation

From: Philip Oakley <philipoakley@iee.org>
Date: Jun 16, 2014, 19:57 UTC
Message-ID: <05EDF0921017440B962382667FE945B7@PhilipOakley>
In-Reply-To: <xmqq8uowr8ki.fsf@gitster.dls.corp.google.com>

From: "Junio C Hamano" <gitster@pobox.com>

Show 11 quoted lines

> Philip Oakley <philipoakley@iee.org> writes:
>
>> Clarify error message puntuation to reduce review workload [1].
>>
>> [1] http://article.gmane.org/gmane.comp.version-control.git/251547
>> (see trailing 'nit' item).
>>
>> Signed-off-by: Philip Oakley <philipoakley@iee.org>
>> ---
>
> Hmmm.  Do we really need to spell everything out?

It was more of a case of 'do we often have to provide this guidance in reviews'? The trailing full stop does appear to come up moderately often, along with other punctuation issues. I am on the 'guidance of the wise and education of others' side of the camp, rather than they being rules and regulations (as was recently misunderstood), so lets educate.

I haven't yet had the time to search deeply, but I'm sure I've also seen various bits of guidance on suitability and style of error messages in the last year of so that the section can be rounded out on that front as well (no doubt similar to some of the commit message guidance).

Show 5 quoted lines

>
> I would rather hope that we can rely on our contributors to know Git
> well enough to ask "git grep" after reading the "follow the style of
> existing and surrounding code" rule that governs the overall
> guideline.

I don't see error messages as "code" per se, rather as an attempt at a consistent user interface[*], and the user errors can come from anywhere, so if we have settled on a style, let's say so.

Philip

[*] My distinction here: "code" is a developer interface, "commands and error messages" is the UI.

Show 29 quoted lines

>
>>  Documentation/CodingGuidelines | 7 +++++++
>>  1 file changed, 7 insertions(+)
>>
>> diff --git a/Documentation/CodingGuidelines 
>> b/Documentation/CodingGuidelines
>> index 4d90c77..b2f3442 100644
>> --- a/Documentation/CodingGuidelines
>> +++ b/Documentation/CodingGuidelines
>> @@ -404,6 +404,13 @@ For Python scripts:
>>     documentation for version 2.6 does not mention this prefix, it 
>> has
>>     been supported since version 2.6.0.
>>
>> +Error Messages
>> +
>> + - We typically do not end error messages with a full stop. While
>> +   we've been rather inconsistent in the past, these days we mostly
>> +   settle on no punctuation.
>> +
>> +
>>  Writing Documentation:
>>
>>   Most (if not all) of the documentation pages are written in the
> --
> To unsubscribe from this list: send the line "unsubscribe git" in
> the body of a message to majordomo@vger.kernel.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html
>