{"thread":{"id":"36925","subject":"[PATCH] Coding guideline for Error messages","startedAt":"2014-06-16T12:55:56Z","lastAt":"2014-07-15T19:28:06Z","messageCount":8,"participants":["Philip Oakley","Junio C Hamano","Jeff King"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"244248","messageId":"1402923357-3788-1-git-send-email-philipoakley@iee.org","threadId":"36925","inReplyTo":null,"subject":"[PATCH] Coding guideline for Error messages","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2014-06-16T12:55:56Z","receivedAt":"2014-06-16T12:55:56Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"A recent review comment highlighted the current view on error\nmessage punctuation. I thought it worth recording.\n\nIn the past I've also seen guidance on the error message style.\nThis patch also gives a place for recording such guidance, for\nexample, ensuring that the message is useful to the user, rather\nthan referring to some internal technical issue. I haven't looked\ndeeply for those yet.\n\nPhilip Oakley (1):\n doc: State coding guideline for error message punctuation\n\n Documentation/CodingGuidelines | 7 +++++++\n 1 file changed, 7 insertions(+)\n\n-- \n1.9.4.msysgit.0\n"},{"id":"244249","messageId":"1402923357-3788-2-git-send-email-philipoakley@iee.org","threadId":"36925","inReplyTo":"1402923357-3788-1-git-send-email-philipoakley@iee.org","subject":"[PATCH] doc: State coding guideline for error message punctuation","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2014-06-16T12:55:57Z","receivedAt":"2014-06-16T12:55:57Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"Clarify error message puntuation to reduce review workload [1].\n\n[1] http://article.gmane.org/gmane.comp.version-control.git/251547\n(see trailing 'nit' item).\n\nSigned-off-by: Philip Oakley \n---\n Documentation/CodingGuidelines | 7 +++++++\n 1 file changed, 7 insertions(+)\n\ndiff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines\nindex 4d90c77..b2f3442 100644\n--- a/Documentation/CodingGuidelines\n+++ b/Documentation/CodingGuidelines\n@@ -404,6 +404,13 @@ For Python scripts:\n documentation for version 2.6 does not mention this prefix, it has\n been supported since version 2.6.0.\n \n+Error Messages\n+\n+ - We typically do not end error messages with a full stop. While\n+ we've been rather inconsistent in the past, these days we mostly\n+ settle on no punctuation.\n+\n+\n Writing Documentation:\n \n Most (if not all) of the documentation pages are written in the\n-- \n1.9.4.msysgit.0\n"},{"id":"244331","messageId":"xmqq8uowr8ki.fsf@gitster.dls.corp.google.com","threadId":"36925","inReplyTo":"1402923357-3788-2-git-send-email-philipoakley@iee.org","subject":"Re: [PATCH] doc: State coding guideline for error message punctuation","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2014-06-16T18:52:13Z","receivedAt":"2014-06-16T18:52:13Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Philip Oakley writes:\n\n> Clarify error message puntuation to reduce review workload [1].\n>\n> [1] http://article.gmane.org/gmane.comp.version-control.git/251547\n> (see trailing 'nit' item).\n>\n> Signed-off-by: Philip Oakley \n> ---\n\nHmmm. Do we really need to spell everything out?\n\nI would rather hope that we can rely on our contributors to know Git\nwell enough to ask \"git grep\" after reading the \"follow the style of\nexisting and surrounding code\" rule that governs the overall\nguideline.\n\n> Documentation/CodingGuidelines | 7 +++++++\n> 1 file changed, 7 insertions(+)\n>\n> diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines\n> index 4d90c77..b2f3442 100644\n> --- a/Documentation/CodingGuidelines\n> +++ b/Documentation/CodingGuidelines\n> @@ -404,6 +404,13 @@ For Python scripts:\n> documentation for version 2.6 does not mention this prefix, it has\n> been supported since version 2.6.0.\n> \n> +Error Messages\n> +\n> + - We typically do not end error messages with a full stop. While\n> + we've been rather inconsistent in the past, these days we mostly\n> + settle on no punctuation.\n> +\n> +\n> Writing Documentation:\n> \n> Most (if not all) of the documentation pages are written in the\n"},{"id":"244344","messageId":"05EDF0921017440B962382667FE945B7@PhilipOakley","threadId":"36925","inReplyTo":"xmqq8uowr8ki.fsf@gitster.dls.corp.google.com","subject":"Re: [PATCH] doc: State coding guideline for error message punctuation","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2014-06-16T19:57:47Z","receivedAt":"2014-06-16T19:57:47Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"From: \"Junio C Hamano\" \n> Philip Oakley writes:\n>\n>> Clarify error message puntuation to reduce review workload [1].\n>>\n>> [1] http://article.gmane.org/gmane.comp.version-control.git/251547\n>> (see trailing 'nit' item).\n>>\n>> Signed-off-by: Philip Oakley \n>> ---\n>\n> Hmmm. Do we really need to spell everything out?\nIt was more of a case of 'do we often have to provide this guidance in \nreviews'?\nThe trailing full stop does appear to come up moderately often, along \nwith other punctuation issues. I am on the 'guidance of the wise and \neducation of others' side of the camp, rather than they being rules and \nregulations (as was recently misunderstood), so lets educate.\n\nI haven't yet had the time to search deeply, but I'm sure I've also seen \nvarious bits of guidance on suitability and style of error messages in \nthe last year of so that the section can be rounded out on that front as \nwell (no doubt similar to some of the commit message guidance).\n\n>\n> I would rather hope that we can rely on our contributors to know Git\n> well enough to ask \"git grep\" after reading the \"follow the style of\n> existing and surrounding code\" rule that governs the overall\n> guideline.\n\nI don't see error messages as \"code\" per se, rather as an attempt at a \nconsistent user interface[*], and the user errors can come from \nanywhere, so if we have settled on a style, let's say so.\n\nPhilip\n\n[*] My distinction here: \"code\" is a developer interface, \"commands and \nerror messages\" is the UI.\n\n>\n>> Documentation/CodingGuidelines | 7 +++++++\n>> 1 file changed, 7 insertions(+)\n>>\n>> diff --git a/Documentation/CodingGuidelines \n>> b/Documentation/CodingGuidelines\n>> index 4d90c77..b2f3442 100644\n>> --- a/Documentation/CodingGuidelines\n>> +++ b/Documentation/CodingGuidelines\n>> @@ -404,6 +404,13 @@ For Python scripts:\n>> documentation for version 2.6 does not mention this prefix, it \n>> has\n>> been supported since version 2.6.0.\n>>\n>> +Error Messages\n>> +\n>> + - We typically do not end error messages with a full stop. While\n>> + we've been rather inconsistent in the past, these days we mostly\n>> + settle on no punctuation.\n>> +\n>> +\n>> Writing Documentation:\n>>\n>> Most (if not all) of the documentation pages are written in the\n> --\n> To unsubscribe from this list: send the line \"unsubscribe git\" in\n> the body of a message to majordomo@vger.kernel.org\n> More majordomo info at http://vger.kernel.org/majordomo-info.html\n> \n"},{"id":"244390","messageId":"20140617093759.GA6267@sigill.intra.peff.net","threadId":"36925","inReplyTo":"1402923357-3788-2-git-send-email-philipoakley@iee.org","subject":"Re: [PATCH] doc: State coding guideline for error message punctuation","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2014-06-17T09:37:59Z","receivedAt":"2014-06-17T09:37:59Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Mon, Jun 16, 2014 at 01:55:57PM +0100, Philip Oakley wrote:\n\n> +Error Messages\n> +\n> + - We typically do not end error messages with a full stop. While\n> + we've been rather inconsistent in the past, these days we mostly\n> + settle on no punctuation.\n\nUnlike Junio, I do not mind spelling out guidance for error messages.\nHowever, I do not think the second sentence is adding anything here\n(everything in CodingGuidelines is subject to \"we did not always do it\nthis way, but this is the preferred way now\"). So I'd drop it.\n\nAnd then add in more guidance. Besides \"no full stop\", probably:\n\n 1. do not capitalize (\"unable to open %s\", not \"Unable to open %s\"\n\n 2. maybe something on sentence structure / ordering? We tend to prefer\n \"cannot open 'foo': No such file or directory\" to \"foo: cannot\n open: No such file or directory\".\n\nPerhaps there are others (we do not have to be exhaustive, but it makes\nsense to think for a moment while we are here).\n\n-Peff\n"},{"id":"245713","messageId":"xmqqwqbl6jey.fsf@gitster.dls.corp.google.com","threadId":"36925","inReplyTo":"20140617093759.GA6267@sigill.intra.peff.net","subject":"Re: [PATCH] doc: State coding guideline for error message punctuation","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2014-07-10T20:36:05Z","receivedAt":"2014-07-10T20:36:05Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jeff King writes:\n\n> On Mon, Jun 16, 2014 at 01:55:57PM +0100, Philip Oakley wrote:\n>\n>> +Error Messages\n>> +\n>> + - We typically do not end error messages with a full stop. While\n>> + we've been rather inconsistent in the past, these days we mostly\n>> + settle on no punctuation.\n>\n> Unlike Junio, I do not mind spelling out guidance for error messages.\n> However, I do not think the second sentence is adding anything here\n> (everything in CodingGuidelines is subject to \"we did not always do it\n> this way, but this is the preferred way now\"). So I'd drop it.\n>\n> And then add in more guidance. Besides \"no full stop\", probably:\n>\n> 1. do not capitalize (\"unable to open %s\", not \"Unable to open %s\"\n>\n> 2. maybe something on sentence structure / ordering? We tend to prefer\n> \"cannot open 'foo': No such file or directory\" to \"foo: cannot\n> open: No such file or directory\".\n>\n> Perhaps there are others (we do not have to be exhaustive, but it makes\n> sense to think for a moment while we are here).\n\nI do not want to forever be waiting for a reroll, so let's queue\nthis and advance it to 'next' soonish, and refine the guidelines by\nfurther building on top of it as needed.\n\nThanks.\n\n-- >8 --\nFrom: Philip Oakley \nDate: Mon, 16 Jun 2014 13:55:57 +0100\nSubject: [PATCH] doc: give some guidelines for error messages\n\nClarify error message puntuation to reduce review workload.\n\nSigned-off-by: Philip Oakley \nHelped-by: Jeff King \nSigned-off-by: Junio C Hamano \n---\n Documentation/CodingGuidelines | 9 +++++++++\n 1 file changed, 9 insertions(+)\n\ndiff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines\nindex f424dbd..f4137c6 100644\n--- a/Documentation/CodingGuidelines\n+++ b/Documentation/CodingGuidelines\n@@ -264,6 +264,15 @@ For Python scripts:\n documentation for version 2.6 does not mention this prefix, it has\n been supported since version 2.6.0.\n \n+Error Messages\n+\n+ - Do not end error messages with a full stop.\n+\n+ - Do not capitalize (\"unable to open %s\", not \"Unable to open %s\")\n+\n+ - Say what the error is first (\"cannot open %s\", not \"%s: cannot open\")\n+\n+\n Writing Documentation:\n \n Most (if not all) of the documentation pages are written in the\n-- \n2.0.1-751-ge540734\n"},{"id":"245716","messageId":"20140710204228.GA4459@sigill.intra.peff.net","threadId":"36925","inReplyTo":"xmqqwqbl6jey.fsf@gitster.dls.corp.google.com","subject":"Re: [PATCH] doc: State coding guideline for error message punctuation","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2014-07-10T20:42:28Z","receivedAt":"2014-07-10T20:42:28Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Thu, Jul 10, 2014 at 01:36:05PM -0700, Junio C Hamano wrote:\n\n> > Perhaps there are others (we do not have to be exhaustive, but it makes\n> > sense to think for a moment while we are here).\n> \n> I do not want to forever be waiting for a reroll, so let's queue\n> this and advance it to 'next' soonish, and refine the guidelines by\n> further building on top of it as needed.\n\nYes, that looks good to me. Thanks for moving this forward.\n\n-Peff\n"},{"id":"246084","messageId":"93D8A848078245C2BA36B26D878B5970@PhilipOakley","threadId":"36925","inReplyTo":"xmqqwqbl6jey.fsf@gitster.dls.corp.google.com","subject":"Re: [PATCH] doc: State coding guideline for error message punctuation","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2014-07-15T19:28:06Z","receivedAt":"2014-07-15T19:28:06Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"From: \"Junio C Hamano\" \nSent: Thursday, July 10, 2014 9:36 PM\n> Jeff King writes:\n>\n>> On Mon, Jun 16, 2014 at 01:55:57PM +0100, Philip Oakley wrote:\n>>\n>>> +Error Messages\n>>> +\n>>> + - We typically do not end error messages with a full stop. While\n>>> + we've been rather inconsistent in the past, these days we mostly\n>>> + settle on no punctuation.\n>>\n>> Unlike Junio, I do not mind spelling out guidance for error messages.\n>> However, I do not think the second sentence is adding anything here\n>> (everything in CodingGuidelines is subject to \"we did not always do \n>> it\n>> this way, but this is the preferred way now\"). So I'd drop it.\n>>\n>> And then add in more guidance. Besides \"no full stop\", probably:\n>>\n>> 1. do not capitalize (\"unable to open %s\", not \"Unable to open %s\"\n>>\n>> 2. maybe something on sentence structure / ordering? We tend to \n>> prefer\n>> \"cannot open 'foo': No such file or directory\" to \"foo: cannot\n>> open: No such file or directory\".\n>>\n>> Perhaps there are others (we do not have to be exhaustive, but it \n>> makes\n>> sense to think for a moment while we are here).\n>\n> I do not want to forever be waiting for a reroll, so let's queue\n> this and advance it to 'next' soonish, and refine the guidelines by\n> further building on top of it as needed.\n>\n\nSorry, I've been away on vacation for the last few weeks. I hadn't been \nsure what to include in a re-roll without it gaining too much mission \ncreep.\n\nThanks for keeping an eye on it.\n\n\n> Thanks.\n>\n> -- >8 --\n> From: Philip Oakley \n> Date: Mon, 16 Jun 2014 13:55:57 +0100\n> Subject: [PATCH] doc: give some guidelines for error messages\n>\n> Clarify error message puntuation to reduce review workload.\n>\n> Signed-off-by: Philip Oakley \n> Helped-by: Jeff King \n> Signed-off-by: Junio C Hamano \n> ---\n> Documentation/CodingGuidelines | 9 +++++++++\n> 1 file changed, 9 insertions(+)\n>\n> diff --git a/Documentation/CodingGuidelines \n> b/Documentation/CodingGuidelines\n> index f424dbd..f4137c6 100644\n> --- a/Documentation/CodingGuidelines\n> +++ b/Documentation/CodingGuidelines\n> @@ -264,6 +264,15 @@ For Python scripts:\n> documentation for version 2.6 does not mention this prefix, it has\n> been supported since version 2.6.0.\n>\n> +Error Messages\n> +\n> + - Do not end error messages with a full stop.\n> +\n> + - Do not capitalize (\"unable to open %s\", not \"Unable to open %s\")\n> +\n> + - Say what the error is first (\"cannot open %s\", not \"%s: cannot \n> open\")\n> +\n> +\n> Writing Documentation:\n>\n> Most (if not all) of the documentation pages are written in the\n> -- \n> 2.0.1-751-ge540734\n> \n"}]}