src/doc/rustc-ux-guidelines.md

   1 % Rustc UX guidelines
   2
   3 Don't forget the user. Whether human or another program, such as an IDE, a
   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
   6 learn arcane patterns to compile their program.
   7
   8 ## Error, Warning, Help, Note Messages
   9
  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.
  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
  20 A `help` message is emitted following an `error` or `warning` to give additional
  21 information to the user about how to solve their problem.
  22
  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
  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
  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
  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/error_codes.rs),
  65   [libsyntax](https://github.com/rust-lang/rust/blob/master/src/libsyntax/error_codes.rs),
  66   [librustc_borrowck](https://github.com/rust-lang/rust/blob/master/src/librustc_borrowck/error_codes.rs),
  67   [librustc_metadata](https://github.com/rust-lang/rust/blob/master/src/librustc_metadata/error_codes.rs),
  68   [librustc_mir](https://github.com/rust-lang/rust/blob/master/src/librustc_mir/error_codes.rs),
  69   [librustc_passes](https://github.com/rust-lang/rust/blob/master/src/librustc_passes/error_codes.rs),
  70   [librustc_privacy](https://github.com/rust-lang/rust/blob/master/src/librustc_privacy/error_codes.rs),
  71   [librustc_resolve](https://github.com/rust-lang/rust/blob/master/src/librustc_resolve/error_codes.rs),
  72   [librustc_codegen_llvm](https://github.com/rust-lang/rust/blob/master/src/librustc_codegen_llvm/error_codes.rs),
  73   [librustc_plugin](https://github.com/rust-lang/rust/blob/master/src/librustc_plugin/error_codes.rs),
  74   [librustc_typeck](https://github.com/rust-lang/rust/blob/master/src/librustc_typeck/error_codes.rs).
  75 * Explanations have full markdown support. Use it, especially to highlight
  76 code with backticks.
  77 * When talking about the compiler, call it `the compiler`, not `Rust` or
  78 `rustc`.
  79
  80 ## Compiler Flags
  81
  82 * Flags should be orthogonal to each other. For example, if we'd have a
  83 json-emitting variant of multiple actions `foo` and `bar`, an additional
  84 --json flag is better than adding `--foo-json` and `--bar-json`.
  85 * Always give options a long descriptive name, if only for more
  86 understandable compiler scripts.
  87 * The `--verbose` flag is for adding verbose information to `rustc` output
  88 when not compiling a program. For example, using it with the `--version` flag
  89 gives information about the hashes of the code.
  90 * Experimental flags and options must be guarded behind the `-Z unstable-options` flag.