<!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.28.0</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_codegen_llvm/diagnostics.rs">librustc_codegen_llvm</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>
distrib
>
Mageia
>
6
>
armv7hl
>
media
>
core-updates
>
by-pkgid
>
4e2dbb669434a7691662cb2f0ad38972
>
files
>
11422
