Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: add error messages to the style guide #759

Merged
merged 2 commits into from
Sep 2, 2024
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
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
Loading