Re: Formatting rules for exception messages
2019/9/27 6:23:54 -0700, Florian Weimer : > * mark reinhold: > >> 2019/3/25 5:24:37 -0700, Florian Weimer : >>> Are there any guidelines for formatting exception messages? >>> >>> In particular, I'm interested in the case when the exception message >>> is a (clipped) sentence. Is it supposed to start with a capital >>> letter? >>> >>> If the message refers to a parameter name, the spelling should reflect >>> the name exactly, of course. There seems to be a slight bias towards >>> capitalization, based on a few greps. ... >> >> The first word of any exception message in code that I’ve written, or >> reviewed, is always capitalized unless that word conveys case-sensitive >> technical information (e.g., a parameter name, as you mentioned). This >> improves readability, especially in longer exception messages that >> contain additional punctuation characters. > > Thank you for confirming my observation. Would it make sense to have > these rules documented somewhere? Yes, it would. Perhaps an informational JEP -- I’ll add it to my queue. - Mark
Re: Formatting rules for exception messages
* mark reinhold: > 2019/3/25 5:24:37 -0700, Florian Weimer : >> Are there any guidelines for formatting exception messages? >> >> In particular, I'm interested in the case when the exception message >> is a (clipped) sentence. Is it supposed to start with a capital >> letter? >> >> If the message refers to a parameter name, the spelling should reflect >> the name exactly, of course. There seems to be a slight bias towards >> capitalization, based on a few greps. ... > > The first word of any exception message in code that I’ve written, or > reviewed, is always capitalized unless that word conveys case-sensitive > technical information (e.g., a parameter name, as you mentioned). This > improves readability, especially in longer exception messages that > contain additional punctuation characters. Thank you for confirming my observation. Would it make sense to have these rules documented somewhere?
Re: Formatting rules for exception messages
2019/3/25 5:24:37 -0700, Florian Weimer : > Are there any guidelines for formatting exception messages? > > In particular, I'm interested in the case when the exception message > is a (clipped) sentence. Is it supposed to start with a capital > letter? > > If the message refers to a parameter name, the spelling should reflect > the name exactly, of course. There seems to be a slight bias towards > capitalization, based on a few greps. ... The first word of any exception message in code that I’ve written, or reviewed, is always capitalized unless that word conveys case-sensitive technical information (e.g., a parameter name, as you mentioned). This improves readability, especially in longer exception messages that contain additional punctuation characters. - Mark
Re: Formatting rules for exception messages
Hi Florian,
Appropriate message composition also varies depending on the level
of the library or application. Since you are asking here I'm assuming
this is about OpenJDK exception messages.
Exception messages are very context dependent both on the exception
being thrown and class/method from which they are thrown.
Even though the exception class and the message are propagated and may be
logged or display in another context than they are thrown the message
should tend toward brevity, supplying enough specific information to
identify the cause. It should avoid explaining.
Exceptions are for programmers and operations, not end users.
If an exception text is a full sentence, (noun, verb, direct object, etc.)
it should follow correct grammar and punctuation.
But it would rare that a sentence is appropriate for a Openjdk class
exception.
$.02, Roger
On 03/25/2019 08:24 AM, Florian Weimer wrote:
Are there any guidelines for formatting exception messages?
In particular, I'm interested in the case when the exception message
is a (clipped) sentence. Is it supposed to start with a capital
letter?
If the message refers to a parameter name, the spelling should reflect
the name exactly, of course. There seems to be a slight bias towards
capitalization, based on a few greps. Consider this:
$ LC_ALL=C grep -r 'Exception("[A-Z][^" ]*ing ' src/*/share/classes/ | wc -l
159
$ LC_ALL=C grep -r 'Exception("[a-z][^" ]*ing ' src/*/share/classes/ | wc -l
73
Formatting rules for exception messages
Are there any guidelines for formatting exception messages?
In particular, I'm interested in the case when the exception message
is a (clipped) sentence. Is it supposed to start with a capital
letter?
If the message refers to a parameter name, the spelling should reflect
the name exactly, of course. There seems to be a slight bias towards
capitalization, based on a few greps. Consider this:
$ LC_ALL=C grep -r 'Exception("[A-Z][^" ]*ing ' src/*/share/classes/ | wc -l
159
$ LC_ALL=C grep -r 'Exception("[a-z][^" ]*ing ' src/*/share/classes/ | wc -l
73
