docs: Add a guide for writing diagnostic messages

Change-Id: I552a062931a3ce7a51189559b05c9275f7b205cf
Reviewed-on: https://dawn-review.googlesource.com/c/tint/+/51785
Reviewed-by: David Neto <dneto@google.com>
Kokoro: Kokoro <noreply+kokoro@google.com>
Commit-Queue: Ben Clayton <bclayton@google.com>
This commit is contained in:
Ben Clayton 2021-06-02 20:50:24 +00:00 committed by Tint LUCI CQ
parent f5163d01b5
commit 815cfd14e7
1 changed files with 125 additions and 0 deletions

125
docs/diagnostics_guide.md Normal file
View File

@ -0,0 +1,125 @@
# Tint diagnostic style guide
This guide provides a set of best practices when writing code that emits
diagnostic messages in Tint. These diagnostics are messages presented to the
user in case of error or warning.
The goal of this document is to have our diagnostic messages be clear and
understandable to our users, so that problems are easy to fix, and to try and
keep a consistent style.
## Message style
* Start diagnostic messages with a lower-case letter
* Try to keep the message to a single sentence, if possible
* Do not end the message with punctuation (full stop, exclamation mark, etc)
**Don't:**
```
shader.wgsl:7:1 error: Cannot take the address of expression.
```
**Do:**
```
shader.wgsl:7:1 error: cannot take the address of expression
```
**Justification:**
Succinct messages are more important than grammatical correctness. \
This style matches the style found in most other compilers.
## Prefer to use a `Source` location instead of quoting the code in the message
**Don't:**
```
shader.wgsl:5:7 error: structure 'UBO' requires block decoration
struct UBO {
^^^
```
**Do:**
```
shader.wgsl:5:7 error: structure requires block decoration
struct UBO {
^^^
```
**Justification:**
The highlighted line provides even more contextual information than the quoted
source, and duplicating this information doesn't provide any more help to the
developer.
## Use `note` diagnostics for providing additional links to relevant code
**Don't:**
```
shader.wgsl:5:11 error: type cannot be used in storage class 'storage' as it is non-host-shareable
cond : bool;
^^^^
```
**Do:**
```
shader.wgsl:5:11 error: type cannot be used in storage class 'storage' as it is non-host-shareable
cond : bool;
^^^^
shader.wgsl:8:4 note: while instantiating variable 'StorageBuffer'
var<storage> sb : StorageBuffer;
^^
```
**Justification:**
To properly understand some diagnostics requires looking at more than a single
line. \
Multi-source links can greatly reduce the time it takes to properly
understand a diagnostic message. \
This is especially important for diagnostics raised from complex whole-program
analysis, but can also greatly aid simple diagnostics like symbol collision errors.
## Use simple terminology
**Don't:**
```
shader.wgsl:7:1 error: the originating variable of the left-hand side must not have an access(read) access attribute.
```
**Do:**
```
shader.wgsl:7:1 error: cannot assign to variable with [[access(read)]] decoration
x = 1;
^
shader.wgsl:2:8 note: [[access(read)]] declared here
var x : [[access(read)]] i32;
^^^^^^^^^^^^^^^^
```
**Justification:**
Diagnostics will be read by Web developers who may not be native English
speakers and are unlikely to be familiar with WGSL specification terminology.
Too much technical jargon can be intimidating and confusing. \
Diagnostics should give enough information to explain what's wrong, and most
importantly, give enough information so that a fix actionable.
**Caution:** Be careful to not over simplify. Use the specification terminology
if there's potential ambiguity by not including it.