Jeff King <peff@xxxxxxxx> 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 <philipoakley@xxxxxxx>
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 <philipoakley@xxxxxxx>
Helped-by: Jeff King <peff@xxxxxxxx>
Signed-off-by: Junio C Hamano <gitster@xxxxxxxxx>
---
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
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html