dawn-cmake/docs/diagnostics_guide.md

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.