]>
Commit | Line | Data |
---|---|---|
7453a54e SL |
1 | % Rustc UX guidelines |
2 | ||
92a42be0 | 3 | Don't forget the user. Whether human or another program, such as an IDE, a |
7cac9316 XL |
4 | good user experience with the compiler goes a long way toward making developers' |
5 | lives better. We do not want users to be baffled by compiler output or | |
92a42be0 SL |
6 | learn arcane patterns to compile their program. |
7 | ||
8 | ## Error, Warning, Help, Note Messages | |
9 | ||
7cac9316 XL |
10 | When the compiler detects a problem, it can emit one of the following: an error, a warning, |
11 | a note, or a help message. | |
92a42be0 SL |
12 | |
13 | An `error` is emitted when the compiler detects a problem that makes it unable | |
14 | to compile the program, either because the program is invalid or the | |
15 | programmer has decided to make a specific `warning` into an error. | |
16 | ||
17 | A `warning` is emitted when the compiler detects something odd about a | |
18 | program. For instance, dead code and unused `Result` values. | |
19 | ||
7cac9316 | 20 | A `help` message is emitted following an `error` or `warning` to give additional |
92a42be0 SL |
21 | information to the user about how to solve their problem. |
22 | ||
7cac9316 XL |
23 | A `note` is emitted to identify additional circumstances and parts of the code |
24 | that caused the warning or error. For example, the borrow checker will note any | |
92a42be0 SL |
25 | previous conflicting borrows. |
26 | ||
27 | * Write in plain simple English. If your message, when shown on a – possibly | |
28 | small – screen (which hasn't been cleaned for a while), cannot be understood | |
29 | by a normal programmer, who just came out of bed after a night partying, it's | |
30 | too complex. | |
31 | * `Errors` and `Warnings` should not suggest how to fix the problem. A `Help` | |
32 | message should be emitted instead. | |
33 | * `Error`, `Warning`, `Note`, and `Help` messages start with a lowercase | |
34 | letter and do not end with punctuation. | |
35 | * Error messages should be succinct. Users will see these error messages many | |
36 | times, and more verbose descriptions can be viewed with the `--explain` flag. | |
37 | That said, don't make it so terse that it's hard to understand. | |
38 | * The word "illegal" is illegal. Prefer "invalid" or a more specific word | |
39 | instead. | |
40 | * Errors should document the span of code where they occur – the `span_..` | |
41 | methods allow to easily do this. Also `note` other spans that have contributed | |
42 | to the error if the span isn't too large. | |
43 | * When emitting a message with span, try to reduce the span to the smallest | |
44 | amount possible that still signifies the issue | |
45 | * Try not to emit multiple error messages for the same error. This may require | |
46 | detecting duplicates. | |
47 | * When the compiler has too little information for a specific error message, | |
48 | lobby for annotations for library code that allow adding more. For example see | |
49 | `#[on_unimplemented]`. Use these annotations when available! | |
50 | * Keep in mind that Rust's learning curve is rather steep, and that the | |
51 | compiler messages are an important learning tool. | |
52 | ||
53 | ## Error Explanations | |
54 | ||
55 | Error explanations are long form descriptions of error messages provided with | |
56 | the compiler. They are accessible via the `--explain` flag. Each explanation | |
57 | comes with an example of how to trigger it and advice on how to fix it. | |
58 | ||
7cac9316 XL |
59 | Please read [RFC 1567](https://github.com/rust-lang/rfcs/blob/master/text/1567-long-error-codes-explanation-normalization.md) |
60 | for details on how to format and write long error codes. | |
61 | ||
3157f602 XL |
62 | * All of them are accessible [online](http://doc.rust-lang.org/error-index.html), |
63 | which are auto-generated from rustc source code in different places: | |
64 | [librustc](https://github.com/rust-lang/rust/blob/master/src/librustc/diagnostics.rs), | |
7cac9316 | 65 | [libsyntax](https://github.com/rust-lang/rust/blob/master/src/libsyntax/diagnostics.rs), |
3157f602 XL |
66 | [librustc_borrowck](https://github.com/rust-lang/rust/blob/master/src/librustc_borrowck/diagnostics.rs), |
67 | [librustc_const_eval](https://github.com/rust-lang/rust/blob/master/src/librustc_const_eval/diagnostics.rs), | |
3157f602 XL |
68 | [librustc_metadata](https://github.com/rust-lang/rust/blob/master/src/librustc_metadata/diagnostics.rs), |
69 | [librustc_mir](https://github.com/rust-lang/rust/blob/master/src/librustc_mir/diagnostics.rs), | |
70 | [librustc_passes](https://github.com/rust-lang/rust/blob/master/src/librustc_passes/diagnostics.rs), | |
71 | [librustc_privacy](https://github.com/rust-lang/rust/blob/master/src/librustc_privacy/diagnostics.rs), | |
72 | [librustc_resolve](https://github.com/rust-lang/rust/blob/master/src/librustc_resolve/diagnostics.rs), | |
73 | [librustc_trans](https://github.com/rust-lang/rust/blob/master/src/librustc_trans/diagnostics.rs), | |
7cac9316 | 74 | [librustc_plugin](https://github.com/rust-lang/rust/blob/master/src/librustc_plugin/diagnostics.rs), |
3157f602 | 75 | [librustc_typeck](https://github.com/rust-lang/rust/blob/master/src/librustc_typeck/diagnostics.rs). |
92a42be0 SL |
76 | * Explanations have full markdown support. Use it, especially to highlight |
77 | code with backticks. | |
78 | * When talking about the compiler, call it `the compiler`, not `Rust` or | |
79 | `rustc`. | |
80 | ||
81 | ## Compiler Flags | |
82 | ||
83 | * Flags should be orthogonal to each other. For example, if we'd have a | |
84 | json-emitting variant of multiple actions `foo` and `bar`, an additional | |
85 | --json flag is better than adding `--foo-json` and `--bar-json`. | |
7cac9316 | 86 | * Always give options a long descriptive name, if only for more |
92a42be0 SL |
87 | understandable compiler scripts. |
88 | * The `--verbose` flag is for adding verbose information to `rustc` output | |
89 | when not compiling a program. For example, using it with the `--version` flag | |
90 | gives information about the hashes of the code. | |
7453a54e | 91 | * Experimental flags and options must be guarded behind the `-Z unstable-options` flag. |