From 734244d3573437f416fbace16cd74406404d5a58 Mon Sep 17 00:00:00 2001
From: Ian Bull <irbull@eclipsesource.com>
Date: Wed, 28 Aug 2024 14:07:50 -0700
Subject: [PATCH] docs: add error messages to the style guide

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.

https://github.com/denoland/deno/issues/25269
---
 .../references/contributing/style_guide.md    | 71 +++++++++++++++++++
 1 file changed, 71 insertions(+)

diff --git a/runtime/manual/references/contributing/style_guide.md b/runtime/manual/references/contributing/style_guide.md
index 4395c3c50..173dfb1b6 100644
--- a/runtime/manual/references/contributing/style_guide.md
+++ b/runtime/manual/references/contributing/style_guide.md
@@ -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.