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 into making developer
   5 lives better. We don't 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 either an error, warning,
  11 note, or 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` is emitted following either an `error` or `warning` giving extra
  21 information to the user about how to solve their problem.
  22
  23 A `note` is for identifying additional circumstances and parts of the code
  24 that lead to a 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 * All of them are accessible [online](http://doc.rust-lang.org/error-index.html),
  60   which are auto-generated from rustc source code in different places:
  61   [librustc](https://github.com/rust-lang/rust/blob/master/src/librustc/diagnostics.rs),
  62   [librustc_borrowck](https://github.com/rust-lang/rust/blob/master/src/librustc_borrowck/diagnostics.rs),
  63   [librustc_const_eval](https://github.com/rust-lang/rust/blob/master/src/librustc_const_eval/diagnostics.rs),
  64   [librustc_lint](https://github.com/rust-lang/rust/blob/master/src/librustc_lint/types.rs),
  65   [librustc_metadata](https://github.com/rust-lang/rust/blob/master/src/librustc_metadata/diagnostics.rs),
  66   [librustc_mir](https://github.com/rust-lang/rust/blob/master/src/librustc_mir/diagnostics.rs),
  67   [librustc_passes](https://github.com/rust-lang/rust/blob/master/src/librustc_passes/diagnostics.rs),
  68   [librustc_privacy](https://github.com/rust-lang/rust/blob/master/src/librustc_privacy/diagnostics.rs),
  69   [librustc_resolve](https://github.com/rust-lang/rust/blob/master/src/librustc_resolve/diagnostics.rs),
  70   [librustc_trans](https://github.com/rust-lang/rust/blob/master/src/librustc_trans/diagnostics.rs),
  71   [librustc_typeck](https://github.com/rust-lang/rust/blob/master/src/librustc_typeck/diagnostics.rs).
  72 * Explanations have full markdown support. Use it, especially to highlight
  73 code with backticks.
  74 * When talking about the compiler, call it `the compiler`, not `Rust` or
  75 `rustc`.
  76
  77 ## Compiler Flags
  78
  79 * Flags should be orthogonal to each other. For example, if we'd have a
  80 json-emitting variant of multiple actions `foo` and `bar`, an additional
  81 --json flag is better than adding `--foo-json` and `--bar-json`.
  82 * Always give options a long descriptive name, if only for better
  83 understandable compiler scripts.
  84 * The `--verbose` flag is for adding verbose information to `rustc` output
  85 when not compiling a program. For example, using it with the `--version` flag
  86 gives information about the hashes of the code.
  87 * Experimental flags and options must be guarded behind the `-Z unstable-options` flag.