From: "Junio C Hamano" <gitster@xxxxxxxxx>
Sent: Thursday, July 10, 2014 9:36 PM
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.
Sorry, I've been away on vacation for the last few weeks. I hadn't been
sure what to include in a re-roll without it gaining too much mission
creep.
Thanks for keeping an eye on it.
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