Skip to content

Commit

Permalink
docs: add error messages to the style guide
Browse files Browse the repository at this point in the history
Adds a section to the style guide that explains how to write error
messages for the TypeScript / JavaScript parts of the Deno codebase.

This style guide was used in the `std` and seems to be a good fit for
the runtime as well. It can be updated as we refactor the existing
error messages.

denoland/deno#25269
  • Loading branch information
irbull committed Aug 28, 2024
1 parent 67d3b1a commit 5a9ec3b
Showing 1 changed file with 71 additions and 0 deletions.
71 changes: 71 additions & 0 deletions runtime/manual/references/contributing/style_guide.md
Original file line number Diff line number Diff line change
Expand Up @@ -356,6 +356,77 @@ export function foo(): string {
}
```

### Error Messages

User-facing error messages raised from JavaScript / TypeScript should be clear,
concise, and consistent. Error messages should be in sentence case but should
not end with a period. Error messages should be free of grammatical errors and
typos and written in American English.

> ⚠️ Note that the error message style guide is a work in progress, and not all
> the error messages have been updated to conform to the current styles. Error
> message styles that should be followed:
1. Messages should start with an upper case:

```
Bad: cannot parse input
Good: Cannot parse input
```

2. Messages should not end with a period:

```
Bad: Cannot parse input.
Good: Cannot parse input
```

3. Message should use quotes for values for strings:

```
Bad: Cannot parse input hello, world
Good: Cannot parse input "hello, world"
Good: Attempting to grow buffer by 10 bytes, which would exceed the maximum size of 100 bytes
```

4. Message should state the action that lead to the error:

```
Bad: Invalid input x
Good: Cannot parse input x
```

5. Active voice should be used:

```
Bad: Input x cannot be parsed
Good: Cannot parse input x
```

6. Messages should not use contractions:

```
Bad: Can't parse input x
Good: Cannot parse input x
```

7. Messages should use a colon when providing additional information. Periods
should never be used. Other punctuation may be used as needed:

```
Bad: Cannot parse input x. value is empty
Good: Cannot parse input x: value is empty
```

8. Additional information should describe the current state, if possible, it
should also describe the desired state in an affirmative voice:

```
Bad: Cannot compute the square root for x: value must not be negative
Good: Cannot compute the square root for x: current value is ${x}
Better: Cannot compute the square root for x as x must be >= 0: current value is ${x}
```

### `std`

#### Do not depend on external code.
Expand Down

0 comments on commit 5a9ec3b

Please sign in to comment.