Normalize error message grammar

[jsejcksn]

Is the error grammar in all std mods the same? I think to remember different ones (missing xyz: something, xyz is missing in something, you didn't put xyz in something).

(Originally posted by @timreichen in https://github.com/denoland/std/issues/5476#issuecomment-2255599242)

[jsejcksn]

There's been discussion about messaging grammar in various comments in past issues/PRs, but most were somewhat tangent to the associated contexts. I created this issue as a dedicated place to potentially find alignment.

[timreichen]

Some thoughts to keep this going:

• What grammar structure should be used for errors? Can we establish some rules for guidance?

  • noun-first: input is invalid
  • noun-first, but avoid negative adjectives: input is not valid
  • adjective-first: invalid input

• Should there be a dot at the end of an error message? https://github.com/denoland/std/blob/fab93bb71decf3f103bb26de88c37a9b15c26d11/front_matter/_shared.ts#L43 https://github.com/denoland/std/blob/fab93bb71decf3f103bb26de88c37a9b15c26d11/encoding/base32.ts#L38

• Should error messages start uppercase or lowercase?* https://github.com/denoland/std/blob/fab93bb71decf3f103bb26de88c37a9b15c26d11/front_matter/_shared.ts#L43 https://github.com/denoland/std/blob/fab93bb71decf3f103bb26de88c37a9b15c26d11/crypto/_fnv/mod.ts#L22

• Should error messages have an explanation, on how to avoid the error? https://github.com/denoland/std/blob/fab93bb71decf3f103bb26de88c37a9b15c26d11/encoding/base32.ts#L38 https://github.com/denoland/std/blob/fab93bb71decf3f103bb26de88c37a9b15c26d11/encoding/base32.ts#L47

• Should an error include information, where the error occurred? https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Errors/JSON_bad_parse https://github.com/denoland/std/blob/fab93bb71decf3f103bb26de88c37a9b15c26d11/datetime/_date_time_formatter.ts#L70-L72

• When to use colons, commas, dots*:

  • TypeError: Cannot define property x, object is not extensible (V8-based)
  • TypeError: can't define property "x": Object is not extensible (Firefox)

* different browsers and runtimes have different implementations. example

[jsejcksn]

• TypeError: Cannot define property x, object is not extensible (V8-based)
• TypeError: can't define property "x": Object is not extensible (Firefox)

There's also active and passive voice. Differences can be subtle — for example: perhaps the code in the execution context where the exception occurred wasn't directly responsible for defining the property, but only validating that it was defined (e.g. by some supplied callback). In that case: Property "x" couldn't be defined would be more correct than Couldn't define property "x" if the origin of the error message is the validation code.

[timreichen]

Here is more readable list of questions we might want to use to get to a solution. This is not complete and will be added to if needed. Note that these vary depending on the browser. I would suggest to follow the implementation of V8, which is the first example of each question.

1. Should the message start uppercase or lowercase?

• Cannot parse input
• cannot parse input

2. Should the message end with a dot?

• Cannot parse input
• Cannot parse input.

4. Should the message use quotes for values? What if they are a string?

• Cannot parse input x
• Cannot parse input "x"

5. Should the message state the action that lead to the error?

• Cannot parse input x
• Invalid input x

6. Should the message use active or passive voice?

• Cannot parse input x
• input x cannot be parsed

7. Should the message use contractions?

• Cannot parse input x
• Can't parse input x

8. Should the message use a colon or comma when providing additional information?

• Cannot parse input x, value is empty
• Cannot parse input x: value is empty

9. Should the additional information describe the current state or the requirement/constraint?

• Cannot parse input x, value is empty
• Cannot parse input x, value must not be empty

[iuioiua]

The main requirements of an error message should be:

1. Provide sufficient context for why an error was thrown.
2. Be as clear as possible to the user.
3. Have correct grammar, spelling and punctuation.

Outside of that, nuances in the format of the error message don't yield sufficient benefit to justify having excessive debate.

As for what we can action, we can create a tracking issue that aims to ensure that each package's error messages meet these requirements. We can hone our requirements as we progress this work. WDYT?

[jsejcksn]

@iuioiua While I fully agree with you…

Be as clear as possible to the user

…is very subjective. I also don't want to participate in a lengthy or pedantic bikeshedding discussion. Conversational languages (especially English) suffer from ambiguity, and I only expect that we'd be able to define broadly-applicable, objective requirements for message grammar — something any reviewer could apply to any message in isolation without additional context.

Have correct grammar, spelling and punctuation

To which authority do we defer for this? A concrete style guide would need to be adopted in order to determine what is correct.

[irbull]

I like the list of questions @timreichen posted. -1 for lengthly pedantic bikeshedding discussions; those are the worst... well almost the worst -- inconsistency is even worse. It's better to be consistently wrong than inconsistently right.

I'm happy for a core team member to pick a set of rules, and then we just use them. I was adding an error message a few weeks ago, and I spent too long trying to decide how to structure the message. Having a style guide with these examples would help.

[irbull]

@timreichen I created a change-set with the examples you provided above. https://github.com/denoland/docs/pull/682

As I mentioned in the PR, there are 2 big questions that need to be answered by a core team member:

1. What styles should be used. I don't have any opinion, I just believe in consistency. Those who have worked in the code base the most, have earned the right to decide which styles should be used.
2. Is there any appetite to actually make the error messages consistent / follow a style guide. If not, then having a style guide will be a disservice.

[irbull]

I've started to update the different folders in the std:

Folder	Status	PR
IO	✅	https://github.com/denoland/std/pull/5671
ulid	✅	No obvious problems
crypto	✅	https://github.com/denoland/std/pull/5705
msgpack	✅	https://github.com/denoland/std/pull/5705
toml	✅	https://github.com/denoland/std/pull/5705
data_structures	✅	https://github.com/denoland/std/pull/5705
net	✅	No obvious problems
front_matter	✅	https://github.com/denoland/std/pull/5706
cache	✅	https://github.com/denoland/std/pull/5706
archive	✅	https://github.com/denoland/std/pull/5706
bytes	✅	No obvious problems
datetime	✅	https://github.com/denoland/std/pull/5706
fmt	✅	https://github.com/denoland/std/pull/5706
streams	✅	https://github.com/denoland/std/pull/5718
path	✅	https://github.com/denoland/std/pull/5718
webgpu	✅	https://github.com/denoland/std/pull/5754
async	✅	https://github.com/denoland/std/pull/5758
internal	✅	https://github.com/denoland/std/pull/5766
encoding	✅	https://github.com/denoland/std/pull/5767
cli	✅	https://github.com/denoland/std/pull/5768
assert	✅	~https://github.com/denoland/std/pull/5784 or~ https://github.com/denoland/std/pull/5797
testing	✅	https://github.com/denoland/std/pull/5810
semver	✅	https://github.com/denoland/std/pull/5785
ini	✅	No obvious problems
http	✅	https://github.com/denoland/std/pull/5791
csv	✅	https://github.com/denoland/std/pull/5796
jsonc	✅	https://github.com/denoland/std/pull/5799
media_types	✅	https://github.com/denoland/std/pull/5800
yaml	✅	https://github.com/denoland/std/pull/5806
log	✅	https://github.com/denoland/std/pull/5801
fs	✅	https://github.com/denoland/std/pull/5802
uuid	✅	https://github.com/denoland/std/pull/5803
expect	✅	https://github.com/denoland/std/pull/5811 and https://github.com/denoland/std/pull/5835

[kt3k]

For the further work, I don't think we need to align the error messages only used in test cases. Let's only work on user-facing errors

[kt3k]

The style guide has been landed in #5671

[irbull]

We have included the error message styles to the style guide and taken a pass through all the error messages. I used the following shell command to find errors:

find . -type f -not -path "./coverage/*" -exec grep "throw" -H '{}' \;

Do you think that's enough to close this issue? I'm sure there are more errors that can be improved over time.

[kt3k]

@irbull Sounds good enough for now. Thank you for your contributions!