From: Junio C Hamano Date: Thu, 10 Jul 2014 20:36:05 GMT Subject: Re: [PATCH] doc: State coding guideline for error message punctuation Message-ID: In-Reply-To: <20140617093759.GA6267@sigill.intra.peff.net> Jeff King writes: > On Mon, Jun 16, 2014 at 01:55:57PM +0100, Philip Oakley wrote: > >> +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. > > Unlike Junio, I do not mind spelling out guidance for error messages. > However, I do not think the second sentence is adding anything here > (everything in CodingGuidelines is subject to "we did not always do it > this way, but this is the preferred way now"). So I'd drop it. > > And then add in more guidance. Besides "no full stop", probably: > > 1. do not capitalize ("unable to open %s", not "Unable to open %s" > > 2. maybe something on sentence structure / ordering? We tend to prefer > "cannot open 'foo': No such file or directory" to "foo: cannot > open: No such file or directory". > > Perhaps there are others (we do not have to be exhaustive, but it makes > sense to think for a moment while we are here). I do not want to forever be waiting for a reroll, so let's queue this and advance it to 'next' soonish, and refine the guidelines by further building on top of it as needed. Thanks. -- >8 -- From: Philip Oakley Date: Mon, 16 Jun 2014 13:55:57 +0100 Subject: [PATCH] doc: give some guidelines for error messages Clarify error message puntuation to reduce review workload. Signed-off-by: Philip Oakley Helped-by: Jeff King Signed-off-by: Junio C Hamano --- Documentation/CodingGuidelines | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines index f424dbd..f4137c6 100644 --- a/Documentation/CodingGuidelines +++ b/Documentation/CodingGuidelines @@ -264,6 +264,15 @@ For Python scripts: documentation for version 2.6 does not mention this prefix, it has been supported since version 2.6.0. +Error Messages + + - Do not end error messages with a full stop. + + - Do not capitalize ("unable to open %s", not "Unable to open %s") + + - Say what the error is first ("cannot open %s", not "%s: cannot open") + + Writing Documentation: Most (if not all) of the documentation pages are written in the -- 2.0.1-751-ge540734