% 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 toward making developers’ lives better. We do not 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 one of the following: an error, a warning, a note, or a 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
message is emitted following an error
or warning
to give additional information to the user about how to solve their problem.
A note
is emitted to identify additional circumstances and parts of the code that caused the 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.
Please read RFC 1567 for details on how to format and write long error codes.
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.