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.

and should not suggest how to fix the problem. A message should be emitted instead. Error , Warning , Note , and Help messages start with a lowercase letter and do not end with punctuation.

, , , and 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.

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.?)

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]

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.

flag is for adding verbose information to output when not compiling a program. For example, using it with the 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?