# Pre-RFC?: rustc UX Guidelines **URL:** \ **Category:** Uncategorized\ **Created:** [July 31, 2015, 4:41am UTC](https://internals.rust-lang.org/t/pre-rfc-rustc-ux-guidelines/2419 "2015-07-31T04:41:55Z")\ **Posts on this page:** 20\ **Page:** 1
**Author:** ![Havvy](https://sea2.discourse-cdn.com/flex002/user_avatar/internals.rust-lang.org/havvy/32/178_2.png) [@Havvy](https://internals.rust-lang.org/u/Havvy)\ **Post date:** [July 31, 2015, 4:41am UTC](https://internals.rust-lang.org/t/pre-rfc-rustc-ux-guidelines/2419/1 "2015-07-31T04:41:55Z")
The Rust language has a style guide and it’s followed pretty well. That’s great, but what about the other stylistic aspects of the rustc compiler? Things like how error messages are supposed to be written and other similar things. There’s currently no user experience guidelines document. I sent in a PR for one given some error message stuff, but we probably need an RFC to actually come to an agreement about what our user experience is with the compiler. Areas of user experience that I can think of include error messages, compiler flags, the help file, what is emitted during success, and basically any user facing interface interactions. Here’s what I came up with for a start, but it’s woefully incomplete. For areas where you’ve worked on UX, are there any decisions you made that should be codified into a guidelines document? Do we actually need an RFC for this? Are we going to also want to have guidelines for other projects (cargo, racer, etc.)? ---
**Author:** ![Havvy](https://sea2.discourse-cdn.com/flex002/user_avatar/internals.rust-lang.org/havvy/32/178_2.png) [@Havvy](https://internals.rust-lang.org/u/Havvy)\ **Post date:** [July 31, 2015, 5:59am UTC](https://internals.rust-lang.org/t/pre-rfc-rustc-ux-guidelines/2419/2 "2015-07-31T05:59:58Z")
And for an actual RFC… * * * - Feature Name: ux-guidelines - Start Date: 2015-07-30 - RFC PR: (leave this empty) - Rust Issue: (leave this empty) # Summary This is a conventions RFC to settle and document a number of UX guidelines. - Error Messages - Explain Messages - Compiler flags # Motivation Good user experience is paramount for happy users. We already have informal guidelines, and having them documented makes it easier for new developers to start contributing without regressing on user experience. # Detailed design This RFC includes a number of unrelated UX guidelines broken down into arbitrary subsections. It starts with an overall summary of the goals of these guidelines. Ideally, everything after this paragraph should be copyable into a `ux-guidelines.md` file into the rustc repo. ### Summary 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. And when developer lives are better, they can make their users’ lives better as well. We don’t want users to be baffled by compiler output or learn arcane patterns to compile their program. ### Error, Warning, Help, Note Messages 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. - Write in plain simple English. If your message, when shown on a – possibly small – screen (which hasn’t been cleaned for a while), cannot be understood by a normal programmer, who just came out of bed after a night partying, it’s too complex. - `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. - Error messages should be succinct. Users will see these error messages many times, and more verbose descriptions can be viewed with the `--explain` flag. That said, don’t make it so terse that it’s hard to understand. - The word “illegal” is illegal. Prefer “invalid” or a more specific word instead. - Errors should document the span of code where they occur – the `span_..` methods allow to easily do this. Also note other spans that have contributed to the error, if any (and only if the span isn’t too large – is there a limit btw.?) - When emitting a message with span, try to reduce the span to the smallest amount possible that still signifies the issue - Try not to emit multiple error messages for the same error. This may require detecting duplicates. - When the compiler has too little information for a specific error message, lobby for annotations for library code that allow adding more. (e.g. see #[on\_unimplemented]). Use these annotations when available! - Keep in mind that Rust’s learning curve is rather steep, and that the compiler messages are an important learning tool. ### Error Explanations 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. - All of them are accessible [[https://github.com/rust-lang/rust/blob/master/src/librustc/diagnostics.rs](https://github.com/rust-lang/rust/blob/master/src/librustc/diagnostics.rs)] - Explanations have full markdown support. Use it, especially to highlight code with backticks. - When talking about the compiler, call it `the compiler`, not `Rust` or `rustc`. ### Compiler Flags - Always give options a long descriptive name, if only for better understandable compiler scripts. - The `--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. - Experimental flags must be behind the `-Z` flag. # Drawbacks None. # Alternatives Have no UX guidelines. # Unresolved questions What other UX guidelines exist but aren’t documented anywhere? What happens when a warning or error subsumes another warning or error? How should the UX guidelines be added to in the future? Not every addition will be forcing a new style, but rather, just documenting practice already done. Should they just be added via a Pull Request? ---
**Author:** ![llogiq](https://sea2.discourse-cdn.com/flex002/user_avatar/internals.rust-lang.org/llogiq/32/13692_2.png) [@llogiq](https://internals.rust-lang.org/u/llogiq)\ **Post date:** [July 31, 2015, 12:42pm UTC](https://internals.rust-lang.org/t/pre-rfc-rustc-ux-guidelines/2419/3 "2015-07-31T12:42:05Z")
I have a few other points that should perhaps be documented. - Errors should document the span of code where they occur – the `span_`… methods allow to easily do this. Also `note` other spans that have contributed to the error, if any (and only if the span isn’t too large – is there a limit btw.?) - When emitting a message with span, try to reduce the span to the smallest amount possible that still signifies the issue - Try not to emit multiple error messages for the same error (this may require detecting duplicates) - When the compiler has too little information for a specific error message, lobby for annotations for library code that allow adding more (e.g. see [`#[on_unimplemented]`](https://github.com/rust-lang/rust/pull/20889) – can we stabilize this?). Also use it when available! - Write in plain simple English. If your sentence, when shown on a – possibly small – screen (which hasn’t been cleaned for a while), cannot be understood by a normal programmer, who just came out of bed after a night partying, it’s probably, or some would say obviously, too complex - Keep in mind that Rust’s learning curve is rather steep, and that the compiler messages are an important learning tool By the way, is there a way to report e.g. a warning + help message that both reference a span without repeating the code in the output? ---
**Author:** ![Havvy](https://sea2.discourse-cdn.com/flex002/user_avatar/internals.rust-lang.org/havvy/32/178_2.png) [@Havvy](https://internals.rust-lang.org/u/Havvy)\ **Post date:** [July 31, 2015, 12:48pm UTC](https://internals.rust-lang.org/t/pre-rfc-rustc-ux-guidelines/2419/4 "2015-07-31T12:48:19Z")
That’s a lot of good points. Thanks! I’ve added them wholesale for now, since I need to go to bed. (This includes the questions…) Will edit when I wake up. ---
**Author:** ![DanielFath](https://sea2.discourse-cdn.com/flex002/user_avatar/internals.rust-lang.org/danielfath/32/5372_2.png) [@DanielFath](https://internals.rust-lang.org/u/DanielFath)\ **Post date:** [July 31, 2015, 1:39pm UTC](https://internals.rust-lang.org/t/pre-rfc-rustc-ux-guidelines/2419/5 "2015-07-31T13:39:51Z")
> [@llogiq](#): > > Write in plain simple English. If your sentence, when shown on a – possibly small – screen (which hasn't been cleaned for a while), cannot be understood by a normal programmer, who just came out of bed after a night partying, it's probably, or some would say obviously, too complex Or better. After writing each error [drink enough booze to get tipsy](http://theuserisdrunk.com/). Can you still understand the message you wrote? If yes, then proceed to partying. If not, grab a snack, sober up and rewrite the whole thing, until you can understand it while drunk 🙂 Useful resource: - [news/compiler-errors-for-humans](http://elm-lang.org/blog/compiler-errors-for-humans) ---
**Author:** ![llogiq](https://sea2.discourse-cdn.com/flex002/user_avatar/internals.rust-lang.org/llogiq/32/13692_2.png) [@llogiq](https://internals.rust-lang.org/u/llogiq)\ **Post date:** [July 31, 2015, 2:02pm UTC](https://internals.rust-lang.org/t/pre-rfc-rustc-ux-guidelines/2419/6 "2015-07-31T14:02:33Z")
Sorry, Daniel, but I strongly oppose this, for fear of rampant alcoholism in our community. Therefore I propose a better procedure: 1. Try to ~~obtain~~ borrow a six year old (I only have a five-year old daughter. She has yet to program a single line of code, but at least she assembled her own RasPI, so there’s that) 2. Read the error message to the aforementioned six year old (I do have to translate to German, as her English is a bit sub-par as of yet. I’m not sure if that augmentation of the procedure makes it better or worse) 3. Discuss the error message, what it means and make note of anything a) you have to explain or b) that is misunderstood This method should work even better with a six-year-old who actually codes, but let’s make do with what we have. Bonus points for teaching Rust to six-year-olds. ---
**Author:** ![DanielKeep](https://sea2.discourse-cdn.com/flex002/user_avatar/internals.rust-lang.org/danielkeep/32/1332_2.png) [@DanielKeep](https://internals.rust-lang.org/u/DanielKeep)\ **Post date:** [July 31, 2015, 2:06pm UTC](https://internals.rust-lang.org/t/pre-rfc-rustc-ux-guidelines/2419/7 "2015-07-31T14:06:15Z")
> [@DanielFath](#): > > After writing each error drink enough booze to get tipsy. This unnecessarily discriminates against teetotalers and people who don't drink. > [@llogiq](#): > > obtain a six year old _runs screaming from this thread_ ---
**Author:** ![DanielFath](https://sea2.discourse-cdn.com/flex002/user_avatar/internals.rust-lang.org/danielfath/32/5372_2.png) [@DanielFath](https://internals.rust-lang.org/u/DanielFath)\ **Post date:** [July 31, 2015, 2:11pm UTC](https://internals.rust-lang.org/t/pre-rfc-rustc-ux-guidelines/2419/8 "2015-07-31T14:11:51Z")
@DanielKeep: You are correct. I haven’t took into consideration that some religions prohibit drinking. For shame ☹ I think ilogiq meant as in building a child from scratch. I’ve heard there are [human factories](https://xkcd.com/387/) walking around. You could ask one of them to `Clone` you. Well, `PartialClone` 😉 ---
**Author:** ![llogiq](https://sea2.discourse-cdn.com/flex002/user_avatar/internals.rust-lang.org/llogiq/32/13692_2.png) [@llogiq](https://internals.rust-lang.org/u/llogiq)\ **Post date:** [July 31, 2015, 2:18pm UTC](https://internals.rust-lang.org/t/pre-rfc-rustc-ux-guidelines/2419/9 "2015-07-31T14:18:38Z")
@DanielKeep / @DanielFath: Forgive me if this sounds somewhat macabre, but you do not need to _mutably own_ the child. Perhaps you can [borrow](http://doc.rust-lang.org/stable/std/borrow/trait.Borrow.html) one? ---
**Author:** ![DanielKeep](https://sea2.discourse-cdn.com/flex002/user_avatar/internals.rust-lang.org/danielkeep/32/1332_2.png) [@DanielKeep](https://internals.rust-lang.org/u/DanielKeep)\ **Post date:** [July 31, 2015, 2:18pm UTC](https://internals.rust-lang.org/t/pre-rfc-rustc-ux-guidelines/2419/10 "2015-07-31T14:18:57Z")
> No, officer, you don't understand. A man on the internet told me to obtain a six year old, and I figured the daycare was... yes, a man. Well, OK, they might _not_ be a _man_. You know what the internet is like. > > Could be a dog for all I know... > > What? _No!_ I needed it to read documentation. For a library. Look, it's _quite_ straightforward: I get the six year old, make them read technical documentation and see if they understood it. > > Well I don't know; the instructions didn't _cover_ what to do after that. > > Of _course_ that was in my search history; where else am I supposed to get a small child at short notice? > > No, they don't seem overly fond of me. Also, I have crippling social anxiety. > > Say, can I go now, I need to make a small white square into a green square or recruiters will think I'm not a rockstar programmer. Hey, are you coming back? Hello? > > ... > > Can I at least get the Wi-Fi password? ---
**Author:** ![llogiq](https://sea2.discourse-cdn.com/flex002/user_avatar/internals.rust-lang.org/llogiq/32/13692_2.png) [@llogiq](https://internals.rust-lang.org/u/llogiq)\ **Post date:** [July 31, 2015, 2:21pm UTC](https://internals.rust-lang.org/t/pre-rfc-rustc-ux-guidelines/2419/11 "2015-07-31T14:21:03Z")
Moral of the story: Don’t trust people (or dogs or other entities) on the internet. ---
**Author:** ![DanielFath](https://sea2.discourse-cdn.com/flex002/user_avatar/internals.rust-lang.org/danielfath/32/5372_2.png) [@DanielFath](https://internals.rust-lang.org/u/DanielFath)\ **Post date:** [July 31, 2015, 2:58pm UTC](https://internals.rust-lang.org/t/pre-rfc-rustc-ux-guidelines/2419/12 "2015-07-31T14:58:32Z")
On a more serious note: How would implement stuff like Elm’s advanced help in Rust? Would they even make sense? `--explain` only works to explain what some type of error is, it doesn’t go into detail of your current impl. ---
**Author:** ![llogiq](https://sea2.discourse-cdn.com/flex002/user_avatar/internals.rust-lang.org/llogiq/32/13692_2.png) [@llogiq](https://internals.rust-lang.org/u/llogiq)\ **Post date:** [July 31, 2015, 8:10pm UTC](https://internals.rust-lang.org/t/pre-rfc-rustc-ux-guidelines/2419/13 "2015-07-31T20:10:47Z")
In fact, it _cannot_ go into details of your current code, because it doesn’t know which code to refer to. This _is_ a problem in current Rust, because we _should_ be able to give more direct information (e.g. using `--verbose`). ---
**Author:** ![Wilfred](https://sea2.discourse-cdn.com/flex002/user_avatar/internals.rust-lang.org/wilfred/32/1138_2.png) [@Wilfred](https://internals.rust-lang.org/u/Wilfred)\ **Post date:** [July 31, 2015, 9:26pm UTC](https://internals.rust-lang.org/t/pre-rfc-rustc-ux-guidelines/2419/14 "2015-07-31T21:26:51Z")
Agreed, a set of guidelines covering 'what makes a good warning/error' is really worthwhile. This seems like a useful checklist for good practices. > [@Havvy](#): > > Errors and Warnings should not suggest how to fix the problem. However, this surprised me: I love useful suggestions when I've made a mistake. As a beginner rust programmer, when rustc says 'did you mean...' or 'consider adding...' it's usually right. What don't you like about suggestions? ---
**Author:** ![llogiq](https://sea2.discourse-cdn.com/flex002/user_avatar/internals.rust-lang.org/llogiq/32/13692_2.png) [@llogiq](https://internals.rust-lang.org/u/llogiq)\ **Post date:** [July 31, 2015, 9:41pm UTC](https://internals.rust-lang.org/t/pre-rfc-rustc-ux-guidelines/2419/15 "2015-07-31T21:41:52Z")
That should be a `help`, which is an additional message to the warning/error. ---
**Author:** ![Havvy](https://sea2.discourse-cdn.com/flex002/user_avatar/internals.rust-lang.org/havvy/32/178_2.png) [@Havvy](https://internals.rust-lang.org/u/Havvy)\ **Post date:** [July 31, 2015, 10:29pm UTC](https://internals.rust-lang.org/t/pre-rfc-rustc-ux-guidelines/2419/16 "2015-07-31T22:29:41Z")
I’d especially like to get some guidelines on compiler flags. Anybody who’s worked on compiler flags have some wisdom on how to properly design them? Possibly even advice on when to and when not to add new flags? ---
**Author:** ![Nashenas88](https://sea2.discourse-cdn.com/flex002/user_avatar/internals.rust-lang.org/nashenas88/32/3537_2.png) [@Nashenas88](https://internals.rust-lang.org/u/Nashenas88)\ **Post date:** [August 1, 2015, 11:39pm UTC](https://internals.rust-lang.org/t/pre-rfc-rustc-ux-guidelines/2419/17 "2015-08-01T23:39:25Z")
I also feel that the distinction between note and help hasn’t been clear in the implementations. Sometimes I see notes that I would think would be help messages. Having documentation on this as well would be helpful. ---
**Author:** ![llogiq](https://sea2.discourse-cdn.com/flex002/user_avatar/internals.rust-lang.org/llogiq/32/13692_2.png) [@llogiq](https://internals.rust-lang.org/u/llogiq)\ **Post date:** [August 1, 2015, 11:51pm UTC](https://internals.rust-lang.org/t/pre-rfc-rustc-ux-guidelines/2419/18 "2015-08-01T23:51:25Z")
Agreed, a bit more documentation would go a long way. Then again, I’ve written a lot of code without reading much of the docs we _have_, so I’m partially to blame for the instances in clippy where we `note` where we could have `help`ed. Havvy: I think I can add two important points regarding command line flags: - Don’t forget the user: This includes humans (which as we know are prone to errors, but able to do great things), as well as other programs (e.g. any IDE that wishes to somehow display our compiler output). - Always give a long, descriptive option name, too (if only for better understandable compile scripts). ---
**Author:** ![Havvy](https://sea2.discourse-cdn.com/flex002/user_avatar/internals.rust-lang.org/havvy/32/178_2.png) [@Havvy](https://internals.rust-lang.org/u/Havvy)\ **Post date:** [August 3, 2015, 12:49pm UTC](https://internals.rust-lang.org/t/pre-rfc-rustc-ux-guidelines/2419/19 "2015-08-03T12:49:29Z")
The first one makes a good summary for UX in general. I added a summary section with that. The second one I added to the document. So now there’s a singular UX guideline for command line flags. ---
**Author:** ![llogiq](https://sea2.discourse-cdn.com/flex002/user_avatar/internals.rust-lang.org/llogiq/32/13692_2.png) [@llogiq](https://internals.rust-lang.org/u/llogiq)\ **Post date:** [August 3, 2015, 4:50pm UTC](https://internals.rust-lang.org/t/pre-rfc-rustc-ux-guidelines/2419/20 "2015-08-03T16:50:47Z")
One thing I’d like to see is verbose messages – we do have the `--verbose` command line argument, but I don’t see any code using it. [Next page](https://internals.rust-lang.org/t/pre-rfc-rustc-ux-guidelines/2419.md?page=2)