<!DOCTYPE html> <html lang="en"> <head> <meta charset="utf-8"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <meta name="generator" content="rustdoc"> <title>Rustc UX guidelines</title> <link rel="stylesheet" type="text/css" href="rust.css"> <link rel="shortcut icon" href="https://www.rust-lang.org/favicon.ico"> </head> <body class="rustdoc"> <!--[if lte IE 8]> <div class="warning"> This old browser is unsupported and will most likely display funky things. </div> <![endif]--> <div id="versioninfo"> <img src="https://www.rust-lang.org/logos/rust-logo-32x32-blk.png" width="32" height="32" alt="Rust logo"><br> <span class="white-sticker"><a href="https://www.rust-lang.org">Rust</a> 1.27.1</span><br> <a href="https://github.com/rust-lang/rust/commit/" class="hash white-sticker"></a> </div> <h1 class="title">Rustc UX guidelines</h1> <nav id="TOC"><ul> <li><a href="#error-warning-help-note-messages">0.1 Error, Warning, Help, Note Messages</a><ul></ul></li> <li><a href="#error-explanations">0.2 Error Explanations</a><ul></ul></li> <li><a href="#compiler-flags">0.3 Compiler Flags</a><ul></ul></li></ul></nav><p>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 toward making developers' lives better. We do not want users to be baffled by compiler output or learn arcane patterns to compile their program.</p> <h2 id="error-warning-help-note-messages" class="section-header"><a href="#error-warning-help-note-messages">0.1 Error, Warning, Help, Note Messages</a></h2> <p>When the compiler detects a problem, it can emit one of the following: an error, a warning, a note, or a help message.</p> <p>An <code>error</code> 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 <code>warning</code> into an error.</p> <p>A <code>warning</code> is emitted when the compiler detects something odd about a program. For instance, dead code and unused <code>Result</code> values.</p> <p>A <code>help</code> message is emitted following an <code>error</code> or <code>warning</code> to give additional information to the user about how to solve their problem.</p> <p>A <code>note</code> is emitted to identify additional circumstances and parts of the code that caused the warning or error. For example, the borrow checker will note any previous conflicting borrows.</p> <ul> <li>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.</li> <li><code>Errors</code> and <code>Warnings</code> should not suggest how to fix the problem. A <code>Help</code> message should be emitted instead.</li> <li><code>Error</code>, <code>Warning</code>, <code>Note</code>, and <code>Help</code> messages start with a lowercase letter and do not end with punctuation.</li> <li>Error messages should be succinct. Users will see these error messages many times, and more verbose descriptions can be viewed with the <code>--explain</code> flag. That said, don't make it so terse that it's hard to understand.</li> <li>The word "illegal" is illegal. Prefer "invalid" or a more specific word instead.</li> <li>Errors should document the span of code where they occur – the <code>span_..</code> methods allow to easily do this. Also <code>note</code> other spans that have contributed to the error if the span isn't too large.</li> <li>When emitting a message with span, try to reduce the span to the smallest amount possible that still signifies the issue</li> <li>Try not to emit multiple error messages for the same error. This may require detecting duplicates.</li> <li>When the compiler has too little information for a specific error message, lobby for annotations for library code that allow adding more. For example see <code>#[on_unimplemented]</code>. Use these annotations when available!</li> <li>Keep in mind that Rust's learning curve is rather steep, and that the compiler messages are an important learning tool.</li> </ul> <h2 id="error-explanations" class="section-header"><a href="#error-explanations">0.2 Error Explanations</a></h2> <p>Error explanations are long form descriptions of error messages provided with the compiler. They are accessible via the <code>--explain</code> flag. Each explanation comes with an example of how to trigger it and advice on how to fix it.</p> <p>Please read <a href="https://github.com/rust-lang/rfcs/blob/master/text/1567-long-error-codes-explanation-normalization.md">RFC 1567</a> for details on how to format and write long error codes.</p> <ul> <li>All of them are accessible <a href="http://doc.rust-lang.org/error-index.html">online</a>, which are auto-generated from rustc source code in different places: <a href="https://github.com/rust-lang/rust/blob/master/src/librustc/diagnostics.rs">librustc</a>, <a href="https://github.com/rust-lang/rust/blob/master/src/libsyntax/diagnostics.rs">libsyntax</a>, <a href="https://github.com/rust-lang/rust/blob/master/src/librustc_borrowck/diagnostics.rs">librustc_borrowck</a>, <a href="https://github.com/rust-lang/rust/blob/master/src/librustc_metadata/diagnostics.rs">librustc_metadata</a>, <a href="https://github.com/rust-lang/rust/blob/master/src/librustc_mir/diagnostics.rs">librustc_mir</a>, <a href="https://github.com/rust-lang/rust/blob/master/src/librustc_passes/diagnostics.rs">librustc_passes</a>, <a href="https://github.com/rust-lang/rust/blob/master/src/librustc_privacy/diagnostics.rs">librustc_privacy</a>, <a href="https://github.com/rust-lang/rust/blob/master/src/librustc_resolve/diagnostics.rs">librustc_resolve</a>, <a href="https://github.com/rust-lang/rust/blob/master/src/librustc_trans/diagnostics.rs">librustc_trans</a>, <a href="https://github.com/rust-lang/rust/blob/master/src/librustc_plugin/diagnostics.rs">librustc_plugin</a>, <a href="https://github.com/rust-lang/rust/blob/master/src/librustc_typeck/diagnostics.rs">librustc_typeck</a>.</li> <li>Explanations have full markdown support. Use it, especially to highlight code with backticks.</li> <li>When talking about the compiler, call it <code>the compiler</code>, not <code>Rust</code> or <code>rustc</code>.</li> </ul> <h2 id="compiler-flags" class="section-header"><a href="#compiler-flags">0.3 Compiler Flags</a></h2> <ul> <li>Flags should be orthogonal to each other. For example, if we'd have a json-emitting variant of multiple actions <code>foo</code> and <code>bar</code>, an additional --json flag is better than adding <code>--foo-json</code> and <code>--bar-json</code>.</li> <li>Always give options a long descriptive name, if only for more understandable compiler scripts.</li> <li>The <code>--verbose</code> flag is for adding verbose information to <code>rustc</code> output when not compiling a program. For example, using it with the <code>--version</code> flag gives information about the hashes of the code.</li> <li>Experimental flags and options must be guarded behind the <code>-Z unstable-options</code> flag.</li> </ul> <footer><p> Copyright © 2011 The Rust Project Developers. Licensed under the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a> or the <a href="https://opensource.org/licenses/MIT">MIT license</a>, at your option. </p><p> This file may not be copied, modified, or distributed except according to those terms. </p></footer> </body> </html>