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:
parent
f5163d01b5
commit
815cfd14e7
|
@ -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.
|
Loading…
Reference in New Issue