% Rustc UX guidelines
Don‘t forget the user. Whether human or another program, such as an IDE, a good user experience with the compiler goes a long way into making developer lives better. We don’t want users to be baffled by compiler output or learn arcane patterns to compile their program.
When the compiler detects a problem, it can emit either an error, warning, note, or help message.
An error
is emitted when the compiler detects a problem that makes it unable to compile the program, either because the program is invalid or the programmer has decided to make a specific warning
into an error.
A warning
is emitted when the compiler detects something odd about a program. For instance, dead code and unused Result
values.
A help
is emitted following either an error
or warning
giving extra information to the user about how to solve their problem.
A note
is for identifying additional circumstances and parts of the code that lead to a warning or error. For example, the borrow checker will note any previous conflicting borrows.
Errors
and Warnings
should not suggest how to fix the problem. A Help
message should be emitted instead.Error
, Warning
, Note
, and Help
messages start with a lowercase letter and do not end with punctuation.--explain
flag. That said, don‘t make it so terse that it’s hard to understand.span_..
methods allow to easily do this. Also note
other spans that have contributed to the error if the span isn't too large.#[on_unimplemented]
. Use these annotations when available!Error explanations are long form descriptions of error messages provided with the compiler. They are accessible via the --explain
flag. Each explanation comes with an example of how to trigger it and advice on how to fix it.
the compiler
, not Rust
or rustc
.foo
and bar
, an additional --json flag is better than adding --foo-json
and --bar-json
.--verbose
flag is for adding verbose information to rustc
output when not compiling a program. For example, using it with the --version
flag gives information about the hashes of the code.-Z unstable-options
flag.