<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>docs/dev/style.md - fork/rust-analyzer @ nightly</title>
<meta name="description" content="docs/dev/style.md in fork/rust-analyzer at nightly.">
<meta property="og:title" content="docs/dev/style.md - fork/rust-analyzer @ nightly">
<meta property="og:description" content="docs/dev/style.md in fork/rust-analyzer at nightly.">
<meta property="og:type" content="website">
<meta property="og:site_name" content="git.julia.blue">
<link rel="stylesheet" href="/css/style.css?v=62">
<script type="module" src="/js/main.js?v=62"></script>
</head>
<body>
<main data-ref="nightly" data-tip="40875353a59ea0be83c711e2223f20e6fe283a47">
<noscript>
  <div class="callout">
    <p>
      hey! this is a static git repo viewer. commit diffs, file history,
      older commits and other revisions won't load without javascript.
    </p>
    <p>
      you are still able to view source files on branch/tag tips,
      but the experience is degraded.
    </p>
  </div>
</noscript>
<header class="repo"><div>
<h1>fork/rust-analyzer</h1>
</div>
<pre class="clone">git clone https://git.julia.blue/fork/rust-analyzer</pre>
</header>
<p class="snapshot-commit"><span class="commit-author">bors</span><span class="commit-message" data-commit="df4ed94f2fb7c16daefa1722657216609f0e8d31">Auto merge of #12722 - jonas-schievink:update-urls, r=jonas-schievink</span><span class="snapshot-sha sha" data-commit="df4ed94f2fb7c16daefa1722657216609f0e8d31">df4ed94f2f</span><time datetime="2022-07-08T13:50:20+00:00" title="2022-07-08 13:50:20 +0000">2022-07-08</time></p>
<header class="topbar"><details class="switcher"><summary>nightly</summary><div class="menu"><strong>branches</strong><a href="/fork/rust-analyzer/ref/master/">master</a><strong>tags</strong><a href="/fork/rust-analyzer/ref/2022-06-13/">2022-06-13</a><a href="/fork/rust-analyzer/ref/2022-06-20/">2022-06-20</a><a href="/fork/rust-analyzer/ref/2022-06-27/">2022-06-27</a><a href="/fork/rust-analyzer/ref/2022-07-04/">2022-07-04</a><a href="/fork/rust-analyzer/ref/2022-07-11/">2022-07-11</a><a href="/fork/rust-analyzer/ref/2022-07-18/">2022-07-18</a><a href="/fork/rust-analyzer/ref/2022-07-25/">2022-07-25</a><a class="current" href="/fork/rust-analyzer/ref/nightly/">nightly</a><a class="all" href="/fork/rust-analyzer/refs">all refs →</a></div></details><nav class="crumbs"><a href="/fork/rust-analyzer/">rust-analyzer</a> / <a href="/fork/rust-analyzer/ref/nightly/tree/docs/">docs</a> / <a href="/fork/rust-analyzer/ref/nightly/tree/docs/dev/">dev</a> / <span class="cur">style.md</span></nav>
<span class="view-stats"><span>30.7 KiB</span><span>1172 lines</span></span><span class="actions"><a class="raw" href="/fork/rust-analyzer/raw/a80eebd632961a6ef468658dce53f755fce95c07/docs/dev/style.md">raw</a></span></header>
<div class="markdown-view"><input type="radio" name="markdown-view" id="markdown-rendered" checked><label for="markdown-rendered">rendered</label><input type="radio" name="markdown-view" id="markdown-code"><label for="markdown-code">code</label><section class="readme rendered"><p>Our approach to "clean code" is two-fold:</p>
<ul>
<li>We generally don't block PRs on style changes.</li>
<li>At the same time, all code in rust-analyzer is constantly refactored.</li>
</ul>
<p>It is explicitly OK for a reviewer to flag only some nits in the PR, and then send a follow-up cleanup PR for things which are easier to explain by example, cc-ing the original author.
Sending small cleanup PRs (like renaming a single local variable) is encouraged.</p>
<p>When reviewing pull requests prefer extending this document to leaving
non-reusable comments on the pull request itself.</p>
<h1>General</h1>
<h2>Scale of Changes</h2>
<p>Everyone knows that it's better to send small &amp; focused pull requests.
The problem is, sometimes you <em>have</em> to, eg, rewrite the whole compiler, and that just doesn't fit into a set of isolated PRs.</p>
<p>The main things to keep an eye on are the boundaries between various components.
There are three kinds of changes:</p>
<ol>
<li>
<p>Internals of a single component are changed.
Specifically, you don't change any <code>pub</code> items.
A good example here would be an addition of a new assist.</p>
</li>
<li>
<p>API of a component is expanded.
Specifically, you add a new <code>pub</code> function which wasn't there before.
A good example here would be expansion of assist API, for example, to implement lazy assists or assists groups.</p>
</li>
<li>
<p>A new dependency between components is introduced.
Specifically, you add a <code>pub use</code> reexport from another crate or you add a new line to the <code>[dependencies]</code> section of <code>Cargo.toml</code>.
A good example here would be adding reference search capability to the assists crates.</p>
</li>
</ol>
<p>For the first group, the change is generally merged as long as:</p>
<ul>
<li>it works for the happy case,</li>
<li>it has tests,</li>
<li>it doesn't panic for the unhappy case.</li>
</ul>
<p>For the second group, the change would be subjected to quite a bit of scrutiny and iteration.
The new API needs to be right (or at least easy to change later).
The actual implementation doesn't matter that much.
It's very important to minimize the amount of changed lines of code for changes of the second kind.
Often, you start doing a change of the first kind, only to realize that you need to elevate to a change of the second kind.
In this case, we'll probably ask you to split API changes into a separate PR.</p>
<p>Changes of the third group should be pretty rare, so we don't specify any specific process for them.
That said, adding an innocent-looking <code>pub use</code> is a very simple way to break encapsulation, keep an eye on it!</p>
<p>Note: if you enjoyed this abstract hand-waving about boundaries, you might appreciate
https://www.tedinski.com/2018/02/06/system-boundaries.html</p>
<h2>Crates.io Dependencies</h2>
<p>We try to be very conservative with usage of crates.io dependencies.
Don't use small "helper" crates (exception: <code>itertools</code> and <code>either</code> are allowed).
If there's some general reusable bit of code you need, consider adding it to the <code>stdx</code> crate.
A useful exercise is to read Cargo.lock and see if some <em>transitive</em> dependencies do not make sense for rust-analyzer.</p>
<p><strong>Rationale:</strong> keep compile times low, create ecosystem pressure for faster compiles, reduce the number of things which might break.</p>
<h2>Commit Style</h2>
<p>We don't have specific rules around git history hygiene.
Maintaining clean git history is strongly encouraged, but not enforced.
Use rebase workflow, it's OK to rewrite history during PR review process.
After you are happy with the state of the code, please use <a href="https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History">interactive rebase</a> to squash fixup commits.</p>
<p>Avoid @mentioning people in commit messages and pull request descriptions(they are added to commit message by bors).
Such messages create a lot of duplicate notification traffic during rebases.</p>
<p>If possible, write Pull Request titles and descriptions from the user's perspective:</p>
<pre># GOOD
Make goto definition work inside macros

# BAD
Use original span for FileId
</pre>
<p>This makes it easier to prepare a changelog.</p>
<p>If the change adds a new user-visible functionality, consider recording a GIF with <a href="https://github.com/phw/peek">peek</a> and pasting it into the PR description.</p>
<p>To make writing the release notes easier, you can mark a pull request as a feature, fix, internal change, or minor.
Minor changes are excluded from the release notes, while the other types are distributed in their corresponding sections.
There are two ways to mark this:</p>
<ul>
<li>use a <code>feat: </code>, <code>feature: </code>, <code>fix: </code>, <code>internal: </code> or <code>minor: </code> prefix in the PR title</li>
<li>write <code>changelog [feature|fix|internal|skip] [description]</code> in a comment or in the PR description; the description is optional, and will replace the title if included.</li>
</ul>
<p>These comments don't have to be added by the PR author.
Editing a comment or the PR description or title is also fine, as long as it happens before the release.</p>
<p><strong>Rationale:</strong> clean history is potentially useful, but rarely used.
But many users read changelogs.
Including a description and GIF suitable for the changelog means less work for the maintainers on the release day.</p>
<h2>Clippy</h2>
<p>We don't enforce Clippy.
A number of default lints have high false positive rate.
Selectively patching false-positives with <code>allow(clippy)</code> is considered worse than not using Clippy at all.
There's a <code>cargo lint</code> command which runs a subset of low-FPR lints.
Careful tweaking of <code>lint</code> is welcome.
Of course, applying Clippy suggestions is welcome as long as they indeed improve the code.</p>
<p><strong>Rationale:</strong> see <a href="https://github.com/rust-lang/rust-clippy/issues/5537">rust-lang/clippy#5537</a>.</p>
<h1>Code</h1>
<h2>Minimal Tests</h2>
<p>Most tests in rust-analyzer start with a snippet of Rust code.
These snippets should be minimal -- if you copy-paste a snippet of real code into the tests, make sure to remove everything which could be removed.</p>
<p>It also makes sense to format snippets more compactly (for example, by placing enum definitions like <code>enum E { Foo, Bar }</code> on a single line),
as long as they are still readable.</p>
<p>When using multiline fixtures, use unindented raw string literals:</p>
<pre class="language-rust">    <a-at>#</a-at><a-p>[</a-p><a-at>test</a-at><a-p>]</a-p>
    <a-k>fn</a-k> <a-f>inline_field_shorthand</a-f><a-p>()</a-p> <a-p>{</a-p>
        <a-f>check_assist</a-f><a-p>(</a-p>
            inline_local_variable<a-p>,</a-p>
            <a-s>r#&quot;
struct S { foo: i32}
fn main() {
    let $0foo = 92;
    S { foo }
}
&quot;#</a-s><a-p>,</a-p>
            <a-s>r#&quot;
struct S { foo: i32}
fn main() {
    S { foo: 92 }
}
&quot;#</a-s><a-p>,</a-p>
        <a-p>);</a-p>
    <a-p>}</a-p></pre>
<p><strong>Rationale:</strong></p>
<p>There are many benefits to this:</p>
<ul>
<li>less to read or to scroll past</li>
<li>easier to understand what exactly is tested</li>
<li>less stuff printed during printf-debugging</li>
<li>less time to run test</li>
</ul>
<p>Formatting ensures that you can use your editor's "number of selected characters" feature to correlate offsets with test's source code.</p>
<h2>Marked Tests</h2>
<p>Use
<a href="https://github.com/matklad/cov-mark"><code>cov_mark::hit! / cov_mark::check!</code></a>
when testing specific conditions.
Do not place several marks into a single test or condition.
Do not reuse marks between several tests.</p>
<p><strong>Rationale:</strong> marks provide an easy way to find the canonical test for each bit of code.
This makes it much easier to understand.
More than one mark per test / code branch doesn't add significantly to understanding.</p>
<h2><code>#[should_panic]</code></h2>
<p>Do not use <code>#[should_panic]</code> tests.
Instead, explicitly check for <code>None</code>, <code>Err</code>, etc.</p>
<p><strong>Rationale:</strong> <code>#[should_panic]</code> is a tool for library authors to make sure that the API does not fail silently when misused.
<code>rust-analyzer</code> is not a library, we don't need to test for API misuse, and we have to handle any user input without panics.
Panic messages in the logs from the <code>#[should_panic]</code> tests are confusing.</p>
<h2><code>#[ignore]</code></h2>
<p>Do not <code>#[ignore]</code> tests.
If the test currently does not work, assert the wrong behavior and add a fixme explaining why it is wrong.</p>
<p><strong>Rationale:</strong> noticing when the behavior is fixed, making sure that even the wrong behavior is acceptable (ie, not a panic).</p>
<h2>Function Preconditions</h2>
<p>Express function preconditions in types and force the caller to provide them (rather than checking in callee):</p>
<pre class="language-rust"><a-c>// GOOD</a-c>
<a-k>fn</a-k> <a-f>frobnicate</a-f><a-p>(</a-p><a-v>walrus</a-v><a-p>:</a-p> <a-t>Walrus</a-t><a-p>)</a-p> <a-p>{</a-p>
    ..<a-p>.</a-p><a-pr>
</a-pr><a-p>}</a-p><a-pr>

</a-pr><a-c>// BAD</a-c><a-pr>
</a-pr><a-k>fn</a-k><a-pr> </a-pr><a-f>frobnicate</a-f><a-p>(</a-p><a-v>walrus</a-v><a-p>:</a-p><a-pr> </a-pr><a-t>Option</a-t><a-p>&lt;</a-p><a-t>Walrus</a-t><a-p>&gt;)</a-p><a-pr> </a-pr><a-p>{</a-p><a-pr>
    </a-pr><a-k>let</a-k><a-pr> walrus = </a-pr><a-k>match</a-k><a-pr> walrus </a-pr><a-p>{</a-p><a-pr>
        </a-pr><a-cr>Some</a-cr><a-p>(</a-p><a-pr>it</a-pr><a-p>)</a-p><a-pr> =&gt; it</a-pr><a-p>,</a-p><a-pr>
        </a-pr><a-cr>None</a-cr><a-pr> =&gt; </a-pr><a-k>return</a-k><a-p>,</a-p><a-pr>
    </a-pr><a-p>};</a-p><a-pr>
    ..</a-pr><a-p>.</a-p><a-pr>
</a-pr><a-p>}</a-p></pre>
<p><strong>Rationale:</strong> this makes control flow explicit at the call site.
Call-site has more context, it often happens that the precondition falls out naturally or can be bubbled up higher in the stack.</p>
<p>Avoid splitting precondition check and precondition use across functions:</p>
<pre class="language-rust"><a-c>// GOOD</a-c>
<a-k>fn</a-k> <a-f>main</a-f><a-p>()</a-p> <a-p>{</a-p>
    <a-k>let</a-k> s<a-p>:</a-p> <a-o>&amp;</a-o><a-t>str</a-t> = ..<a-p>.</a-p><a-pr>;</a-pr><a-pr>
    </a-pr><a-k>if</a-k><a-pr> </a-pr><a-k>let</a-k><a-pr> </a-pr><a-cr>Some</a-cr><a-p>(</a-p><a-pr>contents</a-pr><a-p>)</a-p><a-pr> = </a-pr><a-f>string_literal_contents</a-f><a-p>(</a-p><a-pr>s</a-pr><a-p>)</a-p><a-pr> </a-pr><a-p>{</a-p><a-pr>

    </a-pr><a-p>}</a-p><a-pr>
</a-pr><a-p>}</a-p><a-pr>

</a-pr><a-k>fn</a-k><a-pr> </a-pr><a-f>string_literal_contents</a-f><a-p>(</a-p><a-v>s</a-v><a-p>:</a-p><a-pr> </a-pr><a-o>&amp;</a-o><a-t>str</a-t><a-p>)</a-p><a-pr> -&gt; </a-pr><a-t>Option</a-t><a-p>&lt;</a-p><a-o>&amp;</a-o><a-t>str</a-t><a-p>&gt;</a-p><a-pr> </a-pr><a-p>{</a-p><a-pr>
    </a-pr><a-k>if</a-k><a-pr> s</a-pr><a-p>.</a-p><a-f>starts_with</a-f><a-p>(</a-p><a-s>&#39;&quot;&#39;</a-s><a-p>)</a-p><a-pr> &amp;&amp; s</a-pr><a-p>.</a-p><a-f>ends_with</a-f><a-p>(</a-p><a-s>&#39;&quot;&#39;</a-s><a-p>)</a-p><a-pr> </a-pr><a-p>{</a-p><a-pr>
        </a-pr><a-f>Some</a-f><a-p>(</a-p><a-o>&amp;</a-o><a-pr>s</a-pr><a-p>[</a-p><a-co>1</a-co><a-pr>..s</a-pr><a-p>.</a-p><a-f>len</a-f><a-p>()</a-p><a-pr> - </a-pr><a-co>1</a-co><a-p>])</a-p><a-pr>
    </a-pr><a-p>}</a-p><a-pr> </a-pr><a-k>else</a-k><a-pr> </a-pr><a-p>{</a-p><a-pr>
        </a-pr><a-cr>None</a-cr><a-pr>
    </a-pr><a-p>}</a-p><a-pr>
</a-pr><a-p>}</a-p><a-pr>

</a-pr><a-c>// BAD</a-c><a-pr>
</a-pr><a-k>fn</a-k><a-pr> </a-pr><a-f>main</a-f><a-p>()</a-p><a-pr> </a-pr><a-p>{</a-p><a-pr>
    </a-pr><a-k>let</a-k><a-pr> s</a-pr><a-p>:</a-p><a-pr> </a-pr><a-o>&amp;</a-o><a-t>str</a-t><a-pr> = ..</a-pr><a-p>.</a-p><a-pr>;</a-pr><a-pr>
    </a-pr><a-k>if</a-k><a-pr> </a-pr><a-f>is_string_literal</a-f><a-p>(</a-p><a-pr>s</a-pr><a-p>)</a-p><a-pr> </a-pr><a-p>{</a-p><a-pr>
        </a-pr><a-k>let</a-k><a-pr> contents = </a-pr><a-o>&amp;</a-o><a-pr>s</a-pr><a-p>[</a-p><a-co>1</a-co><a-pr>..s</a-pr><a-p>.</a-p><a-f>len</a-f><a-p>()</a-p><a-pr> - </a-pr><a-co>1</a-co><a-p>];</a-p><a-pr>
    </a-pr><a-p>}</a-p><a-pr>
</a-pr><a-p>}</a-p><a-pr>

</a-pr><a-k>fn</a-k><a-pr> </a-pr><a-f>is_string_literal</a-f><a-p>(</a-p><a-v>s</a-v><a-p>:</a-p><a-pr> </a-pr><a-o>&amp;</a-o><a-t>str</a-t><a-p>)</a-p><a-pr> -&gt; </a-pr><a-t>bool</a-t><a-pr> </a-pr><a-p>{</a-p><a-pr>
    s</a-pr><a-p>.</a-p><a-f>starts_with</a-f><a-p>(</a-p><a-s>&#39;&quot;&#39;</a-s><a-p>)</a-p><a-pr> &amp;&amp; s</a-pr><a-p>.</a-p><a-f>ends_with</a-f><a-p>(</a-p><a-s>&#39;&quot;&#39;</a-s><a-p>)</a-p><a-pr>
</a-pr><a-p>}</a-p></pre>
<p>In the "Not as good" version, the precondition that <code>1</code> is a valid char boundary is checked in <code>is_string_literal</code> and used in <code>foo</code>.
In the "Good" version, the precondition check and usage are checked in the same block, and then encoded in the types.</p>
<p><strong>Rationale:</strong> non-local code properties degrade under change.</p>
<p>When checking a boolean precondition, prefer <code>if !invariant</code> to <code>if negated_invariant</code>:</p>
<pre class="language-rust"><a-c>// GOOD</a-c>
<a-k>if</a-k> !<a-p>(</a-p>idx &lt; len<a-p>)</a-p> <a-p>{</a-p>
    <a-k>return</a-k> <a-cr>None</a-cr><a-p>;</a-p>
<a-p>}</a-p>

<a-c>// BAD</a-c>
<a-k>if</a-k> idx &gt;= len <a-p>{</a-p>
    <a-k>return</a-k> <a-cr>None</a-cr><a-p>;</a-p>
<a-p>}</a-p></pre>
<p><strong>Rationale:</strong> it's useful to see the invariant relied upon by the rest of the function clearly spelled out.</p>
<h2>Control Flow</h2>
<p>As a special case of the previous rule, do not hide control flow inside functions, push it to the caller:</p>
<pre class="language-rust"><a-c>// GOOD</a-c>
<a-k>if</a-k> cond <a-p>{</a-p>
    <a-f>f</a-f><a-p>()</a-p>
<a-p>}</a-p>

<a-c>// BAD</a-c>
<a-k>fn</a-k> <a-f>f</a-f><a-p>()</a-p> <a-p>{</a-p>
    <a-k>if</a-k> !cond <a-p>{</a-p>
        <a-k>return</a-k><a-p>;</a-p>
    <a-p>}</a-p>
    ...
<a-p>}</a-p></pre>
<h2>Assertions</h2>
<p>Assert liberally.
Prefer <a href="https://docs.rs/always-assert/0.1.2/always_assert/macro.never.html"><code>stdx::never!</code></a> to standard <code>assert!</code>.</p>
<p><strong>Rationale:</strong> See <a href="https://github.com/rust-lang/rust-analyzer/blob/master/docs/dev/architecture.md#error-handling">cross cutting concern: error handling</a>.</p>
<h2>Getters &amp; Setters</h2>
<p>If a field can have any value without breaking invariants, make the field public.
Conversely, if there is an invariant, document it, enforce it in the "constructor" function, make the field private, and provide a getter.
Never provide setters.</p>
<p>Getters should return borrowed data:</p>
<pre class="language-rust"><a-k>struct</a-k> <a-t>Person</a-t> <a-p>{</a-p>
    <a-c>// Invariant: never empty</a-c>
    <a-pr>first_name</a-pr><a-p>:</a-p> <a-t>String</a-t><a-p>,</a-p>
    <a-pr>middle_name</a-pr><a-p>:</a-p> <a-t>Option</a-t><a-p>&lt;</a-p><a-t>String</a-t><a-p>&gt;</a-p>
<a-p>}</a-p>

<a-c>// GOOD</a-c>
<a-k>impl</a-k> <a-t>Person</a-t> <a-p>{</a-p>
    <a-k>fn</a-k> <a-f>first_name</a-f><a-p>(</a-p><a-o>&amp;</a-o><a-v>self</a-v><a-p>)</a-p> -&gt; <a-o>&amp;</a-o><a-t>str</a-t> <a-p>{</a-p> <a-v>self</a-v><a-p>.</a-p><a-pr>first_name</a-pr><a-p>.</a-p><a-f>as_str</a-f><a-p>()</a-p> <a-p>}</a-p>
    <a-k>fn</a-k> <a-f>middle_name</a-f><a-p>(</a-p><a-o>&amp;</a-o><a-v>self</a-v><a-p>)</a-p> -&gt; <a-t>Option</a-t><a-p>&lt;</a-p><a-o>&amp;</a-o><a-t>str</a-t><a-p>&gt;</a-p> <a-p>{</a-p> <a-v>self</a-v><a-p>.</a-p><a-pr>middle_name</a-pr><a-p>.</a-p><a-f>as_ref</a-f><a-p>()</a-p> <a-p>}</a-p>
<a-p>}</a-p>

<a-c>// BAD</a-c>
<a-k>impl</a-k> <a-t>Person</a-t> <a-p>{</a-p>
    <a-k>fn</a-k> <a-f>first_name</a-f><a-p>(</a-p><a-o>&amp;</a-o><a-v>self</a-v><a-p>)</a-p> -&gt; <a-t>String</a-t> <a-p>{</a-p> <a-v>self</a-v><a-p>.</a-p><a-pr>first_name</a-pr><a-p>.</a-p><a-f>clone</a-f><a-p>()</a-p> <a-p>}</a-p>
    <a-k>fn</a-k> <a-f>middle_name</a-f><a-p>(</a-p><a-o>&amp;</a-o><a-v>self</a-v><a-p>)</a-p> -&gt; <a-o>&amp;</a-o><a-t>Option</a-t><a-p>&lt;</a-p><a-t>String</a-t><a-p>&gt;</a-p> <a-p>{</a-p> <a-o>&amp;</a-o><a-v>self</a-v><a-p>.</a-p><a-pr>middle_name</a-pr> <a-p>}</a-p>
<a-p>}</a-p></pre>
<p><strong>Rationale:</strong> we don't provide public API, it's cheaper to refactor than to pay getters rent.
Non-local code properties degrade under change, privacy makes invariant local.
Borrowed owned types (<code>&amp;String</code>) disclose irrelevant details about internal representation.
Irrelevant (neither right nor wrong) things obscure correctness.</p>
<h2>Useless Types</h2>
<p>More generally, always prefer types on the left</p>
<pre class="language-rust"><a-c>// GOOD      BAD</a-c>
<a-o>&amp;</a-o><a-p>[</a-p><a-cr>T</a-cr><a-p>]</a-p>         <a-o>&amp;</a-o><a-cr>Vec</a-cr>&lt;<a-cr>T</a-cr>&gt;
<a-o>&amp;</a-o>str         <a-o>&amp;</a-o><a-cr>String</a-cr>
<a-cr>Option</a-cr>&lt;<a-o>&amp;</a-o><a-cr>T</a-cr>&gt;   <a-o>&amp;</a-o><a-cr>Option</a-cr>&lt;<a-cr>T</a-cr>&gt;
<a-o>&amp;</a-o><a-cr>Path</a-cr>        <a-o>&amp;</a-o><a-cr>PathBuf</a-cr></pre>
<p><strong>Rationale:</strong> types on the left are strictly more general.
Even when generality is not required, consistency is important.</p>
<h2>Constructors</h2>
<p>Prefer <code>Default</code> to zero-argument <code>new</code> function.</p>
<pre class="language-rust"><a-c>// GOOD</a-c>
<a-at>#</a-at><a-p>[</a-p><a-at>derive</a-at><a-p>(</a-p><a-cr>Default</a-cr><a-p>)]</a-p>
<a-k>struct</a-k> <a-t>Foo</a-t> <a-p>{</a-p>
    <a-pr>bar</a-pr><a-p>:</a-p> <a-t>Option</a-t><a-p>&lt;</a-p><a-t>Bar</a-t><a-p>&gt;</a-p>
<a-p>}</a-p>

<a-c>// BAD</a-c>
<a-k>struct</a-k> <a-t>Foo</a-t> <a-p>{</a-p>
    <a-pr>bar</a-pr><a-p>:</a-p> <a-t>Option</a-t><a-p>&lt;</a-p><a-t>Bar</a-t><a-p>&gt;</a-p>
<a-p>}</a-p>

<a-k>impl</a-k> <a-t>Foo</a-t> <a-p>{</a-p>
    <a-k>fn</a-k> <a-f>new</a-f><a-p>()</a-p> -&gt; <a-t>Foo</a-t> <a-p>{</a-p>
        <a-t>Foo</a-t> <a-p>{</a-p> <a-pr>bar</a-pr><a-p>:</a-p> <a-cr>None</a-cr> <a-p>}</a-p>
    <a-p>}</a-p>
<a-p>}</a-p></pre>
<p>Prefer <code>Default</code> even if it has to be implemented manually.</p>
<p><strong>Rationale:</strong> less typing in the common case, uniformity.</p>
<p>Use <code>Vec::new</code> rather than <code>vec![]</code>.</p>
<p><strong>Rationale:</strong> uniformity, strength reduction.</p>
<p>Avoid using "dummy" states to implement a <code>Default</code>.
If a type doesn't have a sensible default, empty value, don't hide it.
Let the caller explicitly decide what the right initial state is.</p>
<h2>Functions Over Objects</h2>
<p>Avoid creating "doer" objects.
That is, objects which are created only to execute a single action.</p>
<pre class="language-rust"><a-c>// GOOD</a-c>
<a-f>do_thing</a-f><a-p>(</a-p>arg1<a-p>,</a-p> arg2<a-p>);</a-p>

<a-c>// BAD</a-c>
<a-t>ThingDoer</a-t><a-p>::</a-p><a-f>new</a-f><a-p>(</a-p>arg1<a-p>,</a-p> arg2<a-p>).</a-p><a-f>do</a-f><a-p>();</a-p></pre>
<p>Note that this concerns only outward API.
When implementing <code>do_thing</code>, it might be very useful to create a context object.</p>
<pre class="language-rust"><a-k>pub</a-k> <a-k>fn</a-k> <a-f>do_thing</a-f><a-p>(</a-p><a-v>arg1</a-v><a-p>:</a-p> <a-t>Arg1</a-t><a-p>,</a-p> <a-v>arg2</a-v><a-p>:</a-p> <a-t>Arg2</a-t><a-p>)</a-p> -&gt; <a-t>Res</a-t> <a-p>{</a-p>
    <a-k>let</a-k> <a-k>mut</a-k> ctx = <a-t>Ctx</a-t> <a-p>{</a-p> arg1<a-p>,</a-p> arg2 <a-p>};</a-p>
    ctx<a-p>.</a-p><a-f>run</a-f><a-p>()</a-p>
<a-p>}</a-p>

<a-k>struct</a-k> <a-t>Ctx</a-t> <a-p>{</a-p>
    <a-pr>arg1</a-pr><a-p>:</a-p> <a-t>Arg1</a-t><a-p>,</a-p> <a-pr>arg2</a-pr><a-p>:</a-p> <a-t>Arg2</a-t>
<a-p>}</a-p>

<a-k>impl</a-k> <a-t>Ctx</a-t> <a-p>{</a-p>
    <a-k>fn</a-k> <a-f>run</a-f><a-p>(</a-p><a-v>self</a-v><a-p>)</a-p> -&gt; <a-t>Res</a-t> <a-p>{</a-p>
        ..<a-p>.</a-p><a-pr>
    </a-pr><a-p>}</a-p><a-pr>
</a-pr><a-p>}</a-p></pre>
<p>The difference is that <code>Ctx</code> is an impl detail here.</p>
<p>Sometimes a middle ground is acceptable if this can save some busywork:</p>
<pre class="language-rust"><a-t>ThingDoer</a-t><a-p>::</a-p><a-f>do</a-f><a-p>(</a-p>arg1<a-p>,</a-p> arg2<a-p>);</a-p>

<a-k>pub</a-k> <a-k>struct</a-k> <a-t>ThingDoer</a-t> <a-p>{</a-p>
    <a-pr>arg1</a-pr><a-p>:</a-p> <a-t>Arg1</a-t><a-p>,</a-p> <a-pr>arg2</a-pr><a-p>:</a-p> <a-t>Arg2</a-t><a-p>,</a-p>
<a-p>}</a-p>

<a-k>impl</a-k> <a-t>ThingDoer</a-t> <a-p>{</a-p>
    <a-k>pub</a-k> <a-k>fn</a-k> <a-f>do</a-f><a-p>(</a-p><a-v>arg1</a-v><a-p>:</a-p> <a-t>Arg1</a-t><a-p>,</a-p> <a-v>arg2</a-v><a-p>:</a-p> <a-t>Arg2</a-t><a-p>)</a-p> -&gt; <a-t>Res</a-t> <a-p>{</a-p>
        <a-t>ThingDoer</a-t> <a-p>{</a-p> arg1<a-p>,</a-p> arg2 <a-p>}.</a-p><a-f>run</a-f><a-p>()</a-p>
    <a-p>}</a-p>
    <a-k>fn</a-k> <a-f>run</a-f><a-p>(</a-p><a-v>self</a-v><a-p>)</a-p> -&gt; <a-t>Res</a-t> <a-p>{</a-p>
        ..<a-p>.</a-p><a-pr>
    </a-pr><a-p>}</a-p><a-pr>
</a-pr><a-p>}</a-p></pre>
<p><strong>Rationale:</strong> not bothering the caller with irrelevant details, not mixing user API with implementor API.</p>
<h2>Functions with many parameters</h2>
<p>Avoid creating functions with many optional or boolean parameters.
Introduce a <code>Config</code> struct instead.</p>
<pre class="language-rust"><a-c>// GOOD</a-c>
<a-k>pub</a-k> <a-k>struct</a-k> <a-t>AnnotationConfig</a-t> <a-p>{</a-p>
    <a-k>pub</a-k> <a-pr>binary_target</a-pr><a-p>:</a-p> <a-t>bool</a-t><a-p>,</a-p>
    <a-k>pub</a-k> <a-pr>annotate_runnables</a-pr><a-p>:</a-p> <a-t>bool</a-t><a-p>,</a-p>
    <a-k>pub</a-k> <a-pr>annotate_impls</a-pr><a-p>:</a-p> <a-t>bool</a-t><a-p>,</a-p>
<a-p>}</a-p>

<a-k>pub</a-k> <a-k>fn</a-k> <a-f>annotations</a-f><a-p>(</a-p>
    <a-v>db</a-v><a-p>:</a-p> <a-o>&amp;</a-o><a-t>RootDatabase</a-t><a-p>,</a-p>
    <a-v>file_id</a-v><a-p>:</a-p> <a-t>FileId</a-t><a-p>,</a-p>
    <a-v>config</a-v><a-p>:</a-p> <a-t>AnnotationConfig</a-t>
<a-p>)</a-p> -&gt; <a-t>Vec</a-t><a-p>&lt;</a-p><a-t>Annotation</a-t><a-p>&gt;</a-p> <a-p>{</a-p>
    ..<a-p>.</a-p><a-pr>
</a-pr><a-p>}</a-p><a-pr>

</a-pr><a-c>// BAD</a-c><a-pr>
</a-pr><a-k>pub</a-k><a-pr> </a-pr><a-k>fn</a-k><a-pr> </a-pr><a-f>annotations</a-f><a-p>(</a-p><a-pr>
    </a-pr><a-v>db</a-v><a-p>:</a-p><a-pr> </a-pr><a-o>&amp;</a-o><a-t>RootDatabase</a-t><a-p>,</a-p><a-pr>
    </a-pr><a-v>file_id</a-v><a-p>:</a-p><a-pr> </a-pr><a-t>FileId</a-t><a-p>,</a-p><a-pr>
    </a-pr><a-v>binary_target</a-v><a-p>:</a-p><a-pr> </a-pr><a-t>bool</a-t><a-p>,</a-p><a-pr>
    </a-pr><a-v>annotate_runnables</a-v><a-p>:</a-p><a-pr> </a-pr><a-t>bool</a-t><a-p>,</a-p><a-pr>
    </a-pr><a-v>annotate_impls</a-v><a-p>:</a-p><a-pr> </a-pr><a-t>bool</a-t><a-p>,</a-p><a-pr>
</a-pr><a-p>)</a-p><a-pr> -&gt; </a-pr><a-t>Vec</a-t><a-p>&lt;</a-p><a-t>Annotation</a-t><a-p>&gt;</a-p><a-pr> </a-pr><a-p>{</a-p><a-pr>
    ..</a-pr><a-p>.</a-p><a-pr>
</a-pr><a-p>}</a-p></pre>
<p><strong>Rationale:</strong> reducing churn.
If the function has many parameters, they most likely change frequently.
By packing them into a struct we protect all intermediary functions from changes.</p>
<p>Do not implement <code>Default</code> for the <code>Config</code> struct, the caller has more context to determine better defaults.
Do not store <code>Config</code> as a part of the <code>state</code>, pass it explicitly.
This gives more flexibility for the caller.</p>
<p>If there is variation not only in the input parameters, but in the return type as well, consider introducing a <code>Command</code> type.</p>
<pre class="language-rust"><a-c>// MAYBE GOOD</a-c>
<a-k>pub</a-k> <a-k>struct</a-k> <a-t>Query</a-t> <a-p>{</a-p>
    <a-k>pub</a-k> <a-pr>name</a-pr><a-p>:</a-p> <a-t>String</a-t><a-p>,</a-p>
    <a-k>pub</a-k> <a-pr>case_sensitive</a-pr><a-p>:</a-p> <a-t>bool</a-t><a-p>,</a-p>
<a-p>}</a-p>

<a-k>impl</a-k> <a-t>Query</a-t> <a-p>{</a-p>
    <a-k>pub</a-k> <a-k>fn</a-k> <a-f>all</a-f><a-p>(</a-p><a-v>self</a-v><a-p>)</a-p> -&gt; <a-t>Vec</a-t><a-p>&lt;</a-p><a-t>Item</a-t><a-p>&gt;</a-p> <a-p>{</a-p> ..<a-p>.</a-p><a-pr> </a-pr><a-p>}</a-p><a-pr>
    </a-pr><a-k>pub</a-k><a-pr> </a-pr><a-k>fn</a-k><a-pr> </a-pr><a-f>first</a-f><a-p>(</a-p><a-v>self</a-v><a-p>)</a-p><a-pr> -&gt; </a-pr><a-t>Option</a-t><a-p>&lt;</a-p><a-t>Item</a-t><a-p>&gt;</a-p><a-pr> </a-pr><a-p>{</a-p><a-pr> ..</a-pr><a-p>.</a-p><a-pr> </a-pr><a-p>}</a-p><a-pr>
</a-pr><a-p>}</a-p><a-pr>

</a-pr><a-c>// MAYBE BAD</a-c><a-pr>
</a-pr><a-k>fn</a-k><a-pr> </a-pr><a-f>query_all</a-f><a-p>(</a-p><a-v>name</a-v><a-p>:</a-p><a-pr> </a-pr><a-t>String</a-t><a-p>,</a-p><a-pr> </a-pr><a-v>case_sensitive</a-v><a-p>:</a-p><a-pr> </a-pr><a-t>bool</a-t><a-p>)</a-p><a-pr> -&gt; </a-pr><a-t>Vec</a-t><a-p>&lt;</a-p><a-t>Item</a-t><a-p>&gt;</a-p><a-pr> </a-pr><a-p>{</a-p><a-pr> ..</a-pr><a-p>.</a-p><a-pr> </a-pr><a-p>}</a-p><a-pr>
</a-pr><a-k>fn</a-k><a-pr> </a-pr><a-f>query_first</a-f><a-p>(</a-p><a-v>name</a-v><a-p>:</a-p><a-pr> </a-pr><a-t>String</a-t><a-p>,</a-p><a-pr> </a-pr><a-v>case_sensitive</a-v><a-p>:</a-p><a-pr> </a-pr><a-t>bool</a-t><a-p>)</a-p><a-pr> -&gt; </a-pr><a-t>Option</a-t><a-p>&lt;</a-p><a-t>Item</a-t><a-p>&gt;</a-p><a-pr> </a-pr><a-p>{</a-p><a-pr> ..</a-pr><a-p>.</a-p><a-pr> </a-pr><a-p>}</a-p></pre>
<h2>Prefer Separate Functions Over Parameters</h2>
<p>If a function has a <code>bool</code> or an <code>Option</code> parameter, and it is always called with <code>true</code>, <code>false</code>, <code>Some</code> and <code>None</code> literals, split the function in two.</p>
<pre class="language-rust"><a-c>// GOOD</a-c>
<a-k>fn</a-k> <a-f>caller_a</a-f><a-p>()</a-p> <a-p>{</a-p>
    <a-f>foo</a-f><a-p>()</a-p>
<a-p>}</a-p>

<a-k>fn</a-k> <a-f>caller_b</a-f><a-p>()</a-p> <a-p>{</a-p>
    <a-f>foo_with_bar</a-f><a-p>(</a-p><a-t>Bar</a-t><a-p>::</a-p><a-f>new</a-f><a-p>())</a-p>
<a-p>}</a-p>

<a-k>fn</a-k> <a-f>foo</a-f><a-p>()</a-p> <a-p>{</a-p> ..<a-p>.</a-p><a-pr> </a-pr><a-p>}</a-p><a-pr>
</a-pr><a-k>fn</a-k><a-pr> </a-pr><a-f>foo_with_bar</a-f><a-p>(</a-p><a-v>bar</a-v><a-p>:</a-p><a-pr> </a-pr><a-t>Bar</a-t><a-p>)</a-p><a-pr> </a-pr><a-p>{</a-p><a-pr> ..</a-pr><a-p>.</a-p><a-pr> </a-pr><a-p>}</a-p><a-pr>

</a-pr><a-c>// BAD</a-c><a-pr>
</a-pr><a-k>fn</a-k><a-pr> </a-pr><a-f>caller_a</a-f><a-p>()</a-p><a-pr> </a-pr><a-p>{</a-p><a-pr>
    </a-pr><a-f>foo</a-f><a-p>(</a-p><a-cr>None</a-cr><a-p>)</a-p><a-pr>
</a-pr><a-p>}</a-p><a-pr>

</a-pr><a-k>fn</a-k><a-pr> </a-pr><a-f>caller_b</a-f><a-p>()</a-p><a-pr> </a-pr><a-p>{</a-p><a-pr>
    </a-pr><a-f>foo</a-f><a-p>(</a-p><a-f>Some</a-f><a-p>(</a-p><a-t>Bar</a-t><a-p>::</a-p><a-f>new</a-f><a-p>()))</a-p><a-pr>
</a-pr><a-p>}</a-p><a-pr>

</a-pr><a-k>fn</a-k><a-pr> </a-pr><a-f>foo</a-f><a-p>(</a-p><a-v>bar</a-v><a-p>:</a-p><a-pr> </a-pr><a-t>Option</a-t><a-p>&lt;</a-p><a-t>Bar</a-t><a-p>&gt;)</a-p><a-pr> </a-pr><a-p>{</a-p><a-pr> ..</a-pr><a-p>.</a-p><a-pr> </a-pr><a-p>}</a-p></pre>
<p><strong>Rationale:</strong> more often than not, such functions display "<code>false sharing</code>" -- they have additional <code>if</code> branching inside for two different cases.
Splitting the two different control flows into two functions simplifies each path, and remove cross-dependencies between the two paths.
If there's common code between <code>foo</code> and <code>foo_with_bar</code>, extract <em>that</em> into a common helper.</p>
<h2>Appropriate String Types</h2>
<p>When interfacing with OS APIs, use <code>OsString</code>, even if the original source of data is utf-8 encoded.
<strong>Rationale:</strong> cleanly delineates the boundary when the data goes into the OS-land.</p>
<p>Use <code>AbsPathBuf</code> and <code>AbsPath</code> over <code>std::Path</code>.
<strong>Rationale:</strong> rust-analyzer is a long-lived process which handles several projects at the same time.
It is important not to leak cwd by accident.</p>
<h1>Premature Pessimization</h1>
<h2>Avoid Allocations</h2>
<p>Avoid writing code which is slower than it needs to be.
Don't allocate a <code>Vec</code> where an iterator would do, don't allocate strings needlessly.</p>
<pre class="language-rust"><a-c>// GOOD</a-c>
<a-k>use</a-k> itertools<a-p>::</a-p><a-cr>Itertools</a-cr><a-p>;</a-p>

<a-k>let</a-k> <a-p>(</a-p>first_word<a-p>,</a-p> second_word<a-p>)</a-p> = <a-k>match</a-k> text<a-p>.</a-p><a-f>split_ascii_whitespace</a-f><a-p>().</a-p><a-f>collect_tuple</a-f><a-p>()</a-p> <a-p>{</a-p>
    <a-cr>Some</a-cr><a-p>(</a-p>it<a-p>)</a-p> =&gt; it<a-p>,</a-p>
    <a-cr>None</a-cr> =&gt; <a-k>return</a-k><a-p>,</a-p>
<a-p>}</a-p>

<a-c>// BAD</a-c><a-p>
</a-p><a-k>let</a-k><a-p> words = text</a-p><a-p>.</a-p><a-f>split_ascii_whitespace</a-f><a-p>().</a-p><a-f>collect</a-f><a-p>::&lt;</a-p><a-t>Vec</a-t><a-p>&lt;</a-p><a-t>_</a-t><a-p>&gt;&gt;();</a-p><a-p>
</a-p><a-k>if</a-k><a-p> words</a-p><a-p>.</a-p><a-f>len</a-f><a-p>()</a-p><a-p> != </a-p><a-co>2</a-co><a-p> </a-p><a-p>{</a-p><a-p>
    </a-p><a-k>return</a-k><a-p>
</a-p><a-p>}</a-p></pre>
<p><strong>Rationale:</strong> not allocating is almost always faster.</p>
<h2>Push Allocations to the Call Site</h2>
<p>If allocation is inevitable, let the caller allocate the resource:</p>
<pre class="language-rust"><a-c>// GOOD</a-c>
<a-k>fn</a-k> <a-f>frobnicate</a-f><a-p>(</a-p><a-v>s</a-v><a-p>:</a-p> <a-t>String</a-t><a-p>)</a-p> <a-p>{</a-p>
    ..<a-p>.</a-p><a-pr>
</a-pr><a-p>}</a-p><a-pr>

</a-pr><a-c>// BAD</a-c><a-pr>
</a-pr><a-k>fn</a-k><a-pr> </a-pr><a-f>frobnicate</a-f><a-p>(</a-p><a-v>s</a-v><a-p>:</a-p><a-pr> </a-pr><a-o>&amp;</a-o><a-t>str</a-t><a-p>)</a-p><a-pr> </a-pr><a-p>{</a-p><a-pr>
    </a-pr><a-k>let</a-k><a-pr> s = s</a-pr><a-p>.</a-p><a-f>to_string</a-f><a-p>();</a-p><a-pr>
    ..</a-pr><a-p>.</a-p><a-pr>
</a-pr><a-p>}</a-p></pre>
<p><strong>Rationale:</strong> reveals the costs.
It is also more efficient when the caller already owns the allocation.</p>
<h2>Collection Types</h2>
<p>Prefer <code>rustc_hash::FxHashMap</code> and <code>rustc_hash::FxHashSet</code> instead of the ones in <code>std::collections</code>.</p>
<p><strong>Rationale:</strong> they use a hasher that's significantly faster and using them consistently will reduce code size by some small amount.</p>
<h2>Avoid Intermediate Collections</h2>
<p>When writing a recursive function to compute a sets of things, use an accumulator parameter instead of returning a fresh collection.
Accumulator goes first in the list of arguments.</p>
<pre class="language-rust"><a-c>// GOOD</a-c>
<a-k>pub</a-k> <a-k>fn</a-k> <a-f>reachable_nodes</a-f><a-p>(</a-p><a-v>node</a-v><a-p>:</a-p> <a-t>Node</a-t><a-p>)</a-p> -&gt; <a-t>FxHashSet</a-t><a-p>&lt;</a-p><a-t>Node</a-t><a-p>&gt;</a-p> <a-p>{</a-p>
    <a-k>let</a-k> <a-k>mut</a-k> res = <a-t>FxHashSet</a-t><a-p>::</a-p><a-f>default</a-f><a-p>();</a-p>
    <a-f>go</a-f><a-p>(</a-p><a-o>&amp;</a-o><a-k>mut</a-k> res<a-p>,</a-p> node<a-p>);</a-p>
    res
<a-p>}</a-p>
<a-k>fn</a-k> <a-f>go</a-f><a-p>(</a-p><a-v>acc</a-v><a-p>:</a-p> <a-o>&amp;</a-o><a-k>mut</a-k> <a-t>FxHashSet</a-t><a-p>&lt;</a-p><a-t>Node</a-t><a-p>&gt;,</a-p> <a-v>node</a-v><a-p>:</a-p> <a-t>Node</a-t><a-p>)</a-p> <a-p>{</a-p>
    acc<a-p>.</a-p><a-f>insert</a-f><a-p>(</a-p>node<a-p>);</a-p>
    <a-k>for</a-k> n <a-k>in</a-k> node<a-p>.</a-p><a-f>neighbors</a-f><a-p>()</a-p> <a-p>{</a-p>
        <a-f>go</a-f><a-p>(</a-p>acc<a-p>,</a-p> n<a-p>);</a-p>
    <a-p>}</a-p>
<a-p>}</a-p>

<a-c>// BAD</a-c>
<a-k>pub</a-k> <a-k>fn</a-k> <a-f>reachable_nodes</a-f><a-p>(</a-p><a-v>node</a-v><a-p>:</a-p> <a-t>Node</a-t><a-p>)</a-p> -&gt; <a-t>FxHashSet</a-t><a-p>&lt;</a-p><a-t>Node</a-t><a-p>&gt;</a-p> <a-p>{</a-p>
    <a-k>let</a-k> <a-k>mut</a-k> res = <a-t>FxHashSet</a-t><a-p>::</a-p><a-f>default</a-f><a-p>();</a-p>
    res<a-p>.</a-p><a-f>insert</a-f><a-p>(</a-p>node<a-p>);</a-p>
    <a-k>for</a-k> n <a-k>in</a-k> node<a-p>.</a-p><a-f>neighbors</a-f><a-p>()</a-p> <a-p>{</a-p>
        res<a-p>.</a-p><a-f>extend</a-f><a-p>(</a-p><a-f>reachable_nodes</a-f><a-p>(</a-p>n<a-p>));</a-p>
    <a-p>}</a-p>
    res
<a-p>}</a-p></pre>
<p><strong>Rationale:</strong> re-use allocations, accumulator style is more concise for complex cases.</p>
<h2>Avoid Monomorphization</h2>
<p>Avoid making a lot of code type parametric, <em>especially</em> on the boundaries between crates.</p>
<pre class="language-rust"><a-c>// GOOD</a-c>
<a-k>fn</a-k> <a-f>frobnicate</a-f><a-p>(</a-p><a-v>f</a-v><a-p>:</a-p> <a-k>impl</a-k> <a-t>FnMut</a-t><a-p>())</a-p> <a-p>{</a-p>
    <a-f>frobnicate_impl</a-f><a-p>(</a-p><a-o>&amp;</a-o><a-k>mut</a-k> f<a-p>)</a-p>
<a-p>}</a-p>
<a-k>fn</a-k> <a-f>frobnicate_impl</a-f><a-p>(</a-p><a-v>f</a-v><a-p>:</a-p> <a-o>&amp;</a-o><a-k>mut</a-k> <a-k>dyn</a-k> <a-t>FnMut</a-t><a-p>())</a-p> <a-p>{</a-p>
    <a-c>// lots of code</a-c>
<a-p>}</a-p>

<a-c>// BAD</a-c>
<a-k>fn</a-k> <a-f>frobnicate</a-f><a-p>(</a-p><a-v>f</a-v><a-p>:</a-p> <a-k>impl</a-k> <a-t>FnMut</a-t><a-p>())</a-p> <a-p>{</a-p>
    <a-c>// lots of code</a-c>
<a-p>}</a-p></pre>
<p>Avoid <code>AsRef</code> polymorphism, it pays back only for widely used libraries:</p>
<pre class="language-rust"><a-c>// GOOD</a-c>
<a-k>fn</a-k> <a-f>frobnicate</a-f><a-p>(</a-p><a-v>f</a-v><a-p>:</a-p> <a-o>&amp;</a-o><a-t>Path</a-t><a-p>)</a-p> <a-p>{</a-p>
<a-p>}</a-p>

<a-c>// BAD</a-c>
<a-k>fn</a-k> <a-f>frobnicate</a-f><a-p>(</a-p><a-v>f</a-v><a-p>:</a-p> <a-k>impl</a-k> <a-t>AsRef</a-t><a-p>&lt;</a-p><a-t>Path</a-t><a-p>&gt;)</a-p> <a-p>{</a-p>
<a-p>}</a-p></pre>
<p><strong>Rationale:</strong> Rust uses monomorphization to compile generic code, meaning that for each instantiation of a generic functions with concrete types, the function is compiled afresh, <em>per crate</em>.
This allows for exceptionally good performance, but leads to increased compile times.
Runtime performance obeys 80%/20% rule -- only a small fraction of code is hot.
Compile time <strong>does not</strong> obey this rule -- all code has to be compiled.</p>
<h1>Style</h1>
<h2>Order of Imports</h2>
<p>Separate import groups with blank lines.
Use one <code>use</code> per crate.</p>
<p>Module declarations come before the imports.
Order them in "suggested reading order" for a person new to the code base.</p>
<pre class="language-rust"><a-k>mod</a-k> x<a-p>;</a-p>
<a-k>mod</a-k> y<a-p>;</a-p>

<a-c>// First std.</a-c>
<a-k>use</a-k> std<a-p>::{</a-p> ... <a-p>}</a-p>

<a-c>// Second, external crates (both crates.io crates and other rust-analyzer crates).</a-c>
use crate_foo<a-p>::{</a-p> ... <a-p>}</a-p>
use crate_bar<a-p>::{</a-p> ... <a-p>}</a-p>

<a-c>// Then current crate.</a-c>
use <a-k>crate</a-k><a-p>::{}</a-p>

<a-c>// Finally, parent and child modules, but prefer `use crate::`.</a-c>
use <a-k>super</a-k><a-p>::{}</a-p>

<a-c>// Re-exports are treated as item definitions rather than imports, so they go</a-c>
<a-c>// after imports and modules. Use them sparingly.</a-c>
pub <a-k>use</a-k> <a-k>crate</a-k><a-p>::</a-p>x<a-p>::</a-p><a-cr>Z</a-cr><a-p>;</a-p></pre>
<p><strong>Rationale:</strong> consistency.
Reading order is important for new contributors.
Grouping by crate allows spotting unwanted dependencies easier.</p>
<h2>Import Style</h2>
<p>Qualify items from <code>hir</code> and <code>ast</code>.</p>
<pre class="language-rust"><a-c>// GOOD</a-c>
<a-k>use</a-k> syntax<a-p>::</a-p>ast<a-p>;</a-p>

<a-k>fn</a-k> <a-f>frobnicate</a-f><a-p>(</a-p><a-v>func</a-v><a-p>:</a-p> hir<a-p>::</a-p><a-t>Function</a-t><a-p>,</a-p> <a-v>strukt</a-v><a-p>:</a-p> ast<a-p>::</a-p><a-t>Struct</a-t><a-p>)</a-p> <a-p>{}</a-p>

<a-c>// BAD</a-c>
<a-k>use</a-k> hir<a-p>::</a-p><a-cr>Function</a-cr><a-p>;</a-p>
<a-k>use</a-k> syntax<a-p>::</a-p>ast<a-p>::</a-p><a-cr>Struct</a-cr><a-p>;</a-p>

<a-k>fn</a-k> <a-f>frobnicate</a-f><a-p>(</a-p><a-v>func</a-v><a-p>:</a-p> <a-t>Function</a-t><a-p>,</a-p> <a-v>strukt</a-v><a-p>:</a-p> <a-t>Struct</a-t><a-p>)</a-p> <a-p>{}</a-p></pre>
<p><strong>Rationale:</strong> avoids name clashes, makes the layer clear at a glance.</p>
<p>When implementing traits from <code>std::fmt</code> or <code>std::ops</code>, import the module:</p>
<pre class="language-rust"><a-c>// GOOD</a-c>
<a-k>use</a-k> std<a-p>::</a-p>fmt<a-p>;</a-p>

<a-k>impl</a-k> fmt<a-p>::</a-p><a-t>Display</a-t> <a-k>for</a-k> <a-t>RenameError</a-t> <a-p>{</a-p>
    <a-k>fn</a-k> <a-f>fmt</a-f><a-p>(</a-p><a-o>&amp;</a-o><a-v>self</a-v><a-p>,</a-p> <a-v>f</a-v><a-p>:</a-p> <a-o>&amp;</a-o><a-k>mut</a-k> fmt<a-p>::</a-p><a-t>Formatter</a-t><a-p>&lt;</a-p><a-o>&#39;</a-o><a-l>_</a-l><a-p>&gt;)</a-p> -&gt; fmt<a-p>::</a-p><a-t>Result</a-t> <a-p>{</a-p> .. <a-p>}</a-p>
<a-p>}</a-p>

<a-c>// BAD</a-c>
<a-k>impl</a-k> std<a-p>::</a-p>fmt<a-p>::</a-p><a-t>Display</a-t> <a-k>for</a-k> <a-t>RenameError</a-t> <a-p>{</a-p>
    <a-k>fn</a-k> <a-f>fmt</a-f><a-p>(</a-p><a-o>&amp;</a-o><a-v>self</a-v><a-p>,</a-p> <a-v>f</a-v><a-p>:</a-p> <a-o>&amp;</a-o><a-k>mut</a-k> std<a-p>::</a-p>fmt<a-p>::</a-p><a-t>Formatter</a-t><a-p>&lt;</a-p><a-o>&#39;</a-o><a-l>_</a-l><a-p>&gt;)</a-p> -&gt; std<a-p>::</a-p>fmt<a-p>::</a-p><a-t>Result</a-t> <a-p>{</a-p> .. <a-p>}</a-p>
<a-p>}</a-p>

<a-c>// BAD</a-c>
<a-k>use</a-k> std<a-p>::</a-p>ops<a-p>::</a-p><a-cr>Deref</a-cr><a-p>;</a-p>

<a-k>impl</a-k> <a-t>Deref</a-t> <a-k>for</a-k> <a-t>Widget</a-t> <a-p>{</a-p>
    <a-k>type</a-k> <a-t>Target</a-t> = <a-t>str</a-t><a-p>;</a-p>
    <a-k>fn</a-k> <a-f>deref</a-f><a-p>(</a-p><a-o>&amp;</a-o><a-v>self</a-v><a-p>)</a-p> -&gt; <a-o>&amp;</a-o><a-t>str</a-t> <a-p>{</a-p> .. <a-p>}</a-p>
<a-p>}</a-p></pre>
<p><strong>Rationale:</strong> overall, less typing.
Makes it clear that a trait is implemented, rather than used.</p>
<p>Avoid local <code>use MyEnum::*</code> imports.
<strong>Rationale:</strong> consistency.</p>
<p>Prefer <code>use crate::foo::bar</code> to <code>use super::bar</code> or <code>use self::bar::baz</code>.
<strong>Rationale:</strong> consistency, this is the style which works in all cases.</p>
<p>By default, avoid re-exports.
<strong>Rationale:</strong> for non-library code, re-exports introduce two ways to use something and allow for inconsistency.</p>
<h2>Order of Items</h2>
<p>Optimize for the reader who sees the file for the first time, and wants to get a general idea about what's going on.
People read things from top to bottom, so place most important things first.</p>
<p>Specifically, if all items except one are private, always put the non-private item on top.</p>
<pre class="language-rust"><a-c>// GOOD</a-c>
<a-k>pub</a-k><a-p>(</a-p><a-k>crate</a-k><a-p>)</a-p> <a-k>fn</a-k> <a-f>frobnicate</a-f><a-p>()</a-p> <a-p>{</a-p>
    <a-t>Helper</a-t><a-p>::</a-p><a-f>act</a-f><a-p>()</a-p>
<a-p>}</a-p>

<a-at>#</a-at><a-p>[</a-p><a-at>derive</a-at><a-p>(</a-p><a-cr>Default</a-cr><a-p>)]</a-p>
<a-k>struct</a-k> <a-t>Helper</a-t> <a-p>{</a-p> <a-pr>stuff</a-pr><a-p>:</a-p> <a-t>i32</a-t> <a-p>}</a-p>

<a-k>impl</a-k> <a-t>Helper</a-t> <a-p>{</a-p>
    <a-k>fn</a-k> <a-f>act</a-f><a-p>(</a-p><a-o>&amp;</a-o><a-v>self</a-v><a-p>)</a-p> <a-p>{</a-p>

    <a-p>}</a-p>
<a-p>}</a-p>

<a-c>// BAD</a-c>
<a-at>#</a-at><a-p>[</a-p><a-at>derive</a-at><a-p>(</a-p><a-cr>Default</a-cr><a-p>)]</a-p>
<a-k>struct</a-k> <a-t>Helper</a-t> <a-p>{</a-p> <a-pr>stuff</a-pr><a-p>:</a-p> <a-t>i32</a-t> <a-p>}</a-p>

<a-k>pub</a-k><a-p>(</a-p><a-k>crate</a-k><a-p>)</a-p> <a-k>fn</a-k> <a-f>frobnicate</a-f><a-p>()</a-p> <a-p>{</a-p>
    <a-t>Helper</a-t><a-p>::</a-p><a-f>act</a-f><a-p>()</a-p>
<a-p>}</a-p>

<a-k>impl</a-k> <a-t>Helper</a-t> <a-p>{</a-p>
    <a-k>fn</a-k> <a-f>act</a-f><a-p>(</a-p><a-o>&amp;</a-o><a-v>self</a-v><a-p>)</a-p> <a-p>{</a-p>

    <a-p>}</a-p>
<a-p>}</a-p></pre>
<p>If there's a mixture of private and public items, put public items first.</p>
<p>Put <code>struct</code>s and <code>enum</code>s first, functions and impls last. Order type declarations in top-down manner.</p>
<pre class="language-rust"><a-c>// GOOD</a-c>
<a-k>struct</a-k> <a-t>Parent</a-t> <a-p>{</a-p>
    <a-pr>children</a-pr><a-p>:</a-p> <a-t>Vec</a-t><a-p>&lt;</a-p><a-t>Child</a-t><a-p>&gt;</a-p>
<a-p>}</a-p>

<a-k>struct</a-k> <a-t>Child</a-t><a-p>;</a-p>

<a-k>impl</a-k> <a-t>Parent</a-t> <a-p>{</a-p>
<a-p>}</a-p>

<a-k>impl</a-k> <a-t>Child</a-t> <a-p>{</a-p>
<a-p>}</a-p>

<a-c>// BAD</a-c>
<a-k>struct</a-k> <a-t>Child</a-t><a-p>;</a-p>

<a-k>impl</a-k> <a-t>Child</a-t> <a-p>{</a-p>
<a-p>}</a-p>

<a-k>struct</a-k> <a-t>Parent</a-t> <a-p>{</a-p>
    <a-pr>children</a-pr><a-p>:</a-p> <a-t>Vec</a-t><a-p>&lt;</a-p><a-t>Child</a-t><a-p>&gt;</a-p>
<a-p>}</a-p>

<a-k>impl</a-k> <a-t>Parent</a-t> <a-p>{</a-p>
<a-p>}</a-p></pre>
<p><strong>Rationale:</strong> easier to get the sense of the API by visually scanning the file.
If function bodies are folded in the editor, the source code should read as documentation for the public API.</p>
<h2>Context Parameters</h2>
<p>Some parameters are threaded unchanged through many function calls.
They determine the "context" of the operation.
Pass such parameters first, not last.
If there are several context parameters, consider packing them into a <code>struct Ctx</code> and passing it as <code>&amp;self</code>.</p>
<pre class="language-rust"><a-c>// GOOD</a-c>
<a-k>fn</a-k> <a-f>dfs</a-f><a-p>(</a-p><a-v>graph</a-v><a-p>:</a-p> <a-o>&amp;</a-o><a-t>Graph</a-t><a-p>,</a-p> <a-v>v</a-v><a-p>:</a-p> <a-t>Vertex</a-t><a-p>)</a-p> -&gt; <a-t>usize</a-t> <a-p>{</a-p>
    <a-k>let</a-k> <a-k>mut</a-k> visited = <a-t>FxHashSet</a-t><a-p>::</a-p><a-f>default</a-f><a-p>();</a-p>
    <a-k>return</a-k> <a-f>go</a-f><a-p>(</a-p>graph<a-p>,</a-p> <a-o>&amp;</a-o><a-k>mut</a-k> visited<a-p>,</a-p> v<a-p>);</a-p>

    <a-k>fn</a-k> <a-f>go</a-f><a-p>(</a-p><a-v>graph</a-v><a-p>:</a-p> <a-o>&amp;</a-o><a-t>Graph</a-t><a-p>,</a-p> <a-v>visited</a-v><a-p>:</a-p> <a-o>&amp;</a-o><a-k>mut</a-k> <a-t>FxHashSet</a-t><a-p>&lt;</a-p><a-t>Vertex</a-t><a-p>&gt;,</a-p> <a-v>v</a-v><a-p>:</a-p> <a-t>usize</a-t><a-p>)</a-p> -&gt; <a-t>usize</a-t> <a-p>{</a-p>
        ..<a-p>.</a-p><a-pr>
    </a-pr><a-p>}</a-p><a-pr>
</a-pr><a-p>}</a-p><a-pr>

</a-pr><a-c>// BAD</a-c><a-pr>
</a-pr><a-k>fn</a-k><a-pr> </a-pr><a-f>dfs</a-f><a-p>(</a-p><a-v>v</a-v><a-p>:</a-p><a-pr> </a-pr><a-t>Vertex</a-t><a-p>,</a-p><a-pr> </a-pr><a-v>graph</a-v><a-p>:</a-p><a-pr> </a-pr><a-o>&amp;</a-o><a-t>Graph</a-t><a-p>)</a-p><a-pr> -&gt; </a-pr><a-t>usize</a-t><a-pr> </a-pr><a-p>{</a-p><a-pr>
    </a-pr><a-k>fn</a-k><a-pr> </a-pr><a-f>go</a-f><a-p>(</a-p><a-v>v</a-v><a-p>:</a-p><a-pr> </a-pr><a-t>usize</a-t><a-p>,</a-p><a-pr> </a-pr><a-v>graph</a-v><a-p>:</a-p><a-pr> </a-pr><a-o>&amp;</a-o><a-t>Graph</a-t><a-p>,</a-p><a-pr> </a-pr><a-v>visited</a-v><a-p>:</a-p><a-pr> </a-pr><a-o>&amp;</a-o><a-k>mut</a-k><a-pr> </a-pr><a-t>FxHashSet</a-t><a-p>&lt;</a-p><a-t>Vertex</a-t><a-p>&gt;)</a-p><a-pr> -&gt; </a-pr><a-t>usize</a-t><a-pr> </a-pr><a-p>{</a-p><a-pr>
        ..</a-pr><a-p>.</a-p><a-pr>
    </a-pr><a-p>}</a-p><a-pr>

    </a-pr><a-k>let</a-k><a-pr> </a-pr><a-k>mut</a-k><a-pr> visited = </a-pr><a-t>FxHashSet</a-t><a-p>::</a-p><a-f>default</a-f><a-p>();</a-p><a-pr>
    </a-pr><a-f>go</a-f><a-p>(</a-p><a-pr>v</a-pr><a-p>,</a-p><a-pr> graph</a-pr><a-p>,</a-p><a-pr> </a-pr><a-o>&amp;</a-o><a-k>mut</a-k><a-pr> visited</a-pr><a-p>)</a-p><a-pr>
</a-pr><a-p>}</a-p></pre>
<p><strong>Rationale:</strong> consistency.
Context-first works better when non-context parameter is a lambda.</p>
<h2>Variable Naming</h2>
<p>Use boring and long names for local variables (<a href="https://github.com/rust-lang/rust-analyzer/pull/4162#discussion_r417130973">yay code completion</a>).
The default name is a lowercased name of the type: <code>global_state: GlobalState</code>.
Avoid ad-hoc acronyms and contractions, but use the ones that exist consistently (<code>db</code>, <code>ctx</code>, <code>acc</code>).
Prefer American spelling (color, behavior).</p>
<p>Default names:</p>
<ul>
<li><code>res</code> -- "result of the function" local variable</li>
<li><code>it</code> -- I don't really care about the name</li>
<li><code>n_foos</code> -- number of foos (prefer this to <code>foo_count</code>)</li>
<li><code>foo_idx</code> -- index of <code>foo</code></li>
</ul>
<p>Many names in rust-analyzer conflict with keywords.
We use mangled names instead of <code>r#ident</code> syntax:</p>
<pre>crate  -&gt; krate
enum   -&gt; enum_
fn     -&gt; func
impl   -&gt; imp
macro  -&gt; mac
mod    -&gt; module
struct -&gt; strukt
trait  -&gt; trait_
type   -&gt; ty
</pre>
<p><strong>Rationale:</strong> consistency.</p>
<h2>Early Returns</h2>
<p>Do use early returns</p>
<pre class="language-rust"><a-c>// GOOD</a-c>
<a-k>fn</a-k> <a-f>foo</a-f><a-p>()</a-p> -&gt; <a-t>Option</a-t><a-p>&lt;</a-p><a-t>Bar</a-t><a-p>&gt;</a-p> <a-p>{</a-p>
    <a-k>if</a-k> !<a-f>condition</a-f><a-p>()</a-p> <a-p>{</a-p>
        <a-k>return</a-k> <a-cr>None</a-cr><a-p>;</a-p>
    <a-p>}</a-p>

    <a-f>Some</a-f><a-p>(</a-p>..<a-p>.</a-p><a-pr>)</a-pr><a-pr>
</a-pr><a-p>}</a-p><a-pr>

</a-pr><a-c>// BAD</a-c><a-pr>
</a-pr><a-k>fn</a-k><a-pr> </a-pr><a-f>foo</a-f><a-p>()</a-p><a-pr> -&gt; </a-pr><a-t>Option</a-t><a-p>&lt;</a-p><a-t>Bar</a-t><a-p>&gt;</a-p><a-pr> </a-pr><a-p>{</a-p><a-pr>
    </a-pr><a-k>if</a-k><a-pr> </a-pr><a-f>condition</a-f><a-p>()</a-p><a-pr> </a-pr><a-p>{</a-p><a-pr>
        </a-pr><a-f>Some</a-f><a-p>(</a-p><a-pr>..</a-pr><a-p>.</a-p><a-pr>)</a-pr><a-pr>
    </a-pr><a-p>}</a-p><a-pr> </a-pr><a-k>else</a-k><a-pr> </a-pr><a-p>{</a-p><a-pr>
        </a-pr><a-cr>None</a-cr><a-pr>
    </a-pr><a-p>}</a-p><a-pr>
</a-pr><a-p>}</a-p></pre>
<p><strong>Rationale:</strong> reduce cognitive stack usage.</p>
<p>Use <code>return Err(err)</code> to throw an error:</p>
<pre class="language-rust"><a-c>// GOOD</a-c>
<a-k>fn</a-k> <a-f>f</a-f><a-p>()</a-p> -&gt; <a-t>Result</a-t><a-p>&lt;(),</a-p> <a-p>()&gt;</a-p> <a-p>{</a-p>
    <a-k>if</a-k> condition <a-p>{</a-p>
        <a-k>return</a-k> <a-f>Err</a-f><a-p>(());</a-p>
    <a-p>}</a-p>
    <a-f>Ok</a-f><a-p>(())</a-p>
<a-p>}</a-p>

<a-c>// BAD</a-c>
<a-k>fn</a-k> <a-f>f</a-f><a-p>()</a-p> -&gt; <a-t>Result</a-t><a-p>&lt;(),</a-p> <a-p>()&gt;</a-p> <a-p>{</a-p>
    <a-k>if</a-k> condition <a-p>{</a-p>
        <a-f>Err</a-f><a-p>(())</a-p>?<a-p>;</a-p>
    <a-p>}</a-p>
    <a-f>Ok</a-f><a-p>(())</a-p>
<a-p>}</a-p></pre>
<p><strong>Rationale:</strong> <code>return</code> has type <code>!</code>, which allows the compiler to flag dead
code (<code>Err(...)?</code> is of unconstrained generic type <code>T</code>).</p>
<h2>Comparisons</h2>
<p>When doing multiple comparisons use <code>&lt;</code>/<code>&lt;=</code>, avoid <code>&gt;</code>/<code>&gt;=</code>.</p>
<pre class="language-rust"><a-c>// GOOD</a-c>
<a-m>assert!</a-m><a-p>(</a-p>lo &lt;= x &amp;&amp; x &lt;= hi<a-p>);</a-p>
<a-m>assert!</a-m><a-p>(</a-p>r1 &lt; l2 || r2 &lt; l1<a-p>);</a-p>
<a-m>assert!</a-m><a-p>(</a-p>x &lt; y<a-p>);</a-p>
<a-m>assert!</a-m><a-p>(</a-p><a-co>0</a-co> &lt; x<a-p>);</a-p>

<a-c>// BAD</a-c>
<a-m>assert!</a-m><a-p>(</a-p>x &gt;= lo &amp;&amp; x &lt;= hi<a-p>);</a-p>
<a-m>assert!</a-m><a-p>(</a-p>r1 &lt; l2 || l1 &gt; r2<a-p>);</a-p>
<a-m>assert!</a-m><a-p>(</a-p>y &gt; x<a-p>);</a-p>
<a-m>assert!</a-m><a-p>(</a-p>x &gt; <a-co>0</a-co><a-p>);</a-p></pre>
<p><strong>Rationale:</strong> Less-then comparisons are more intuitive, they correspond spatially to <a href="https://en.wikipedia.org/wiki/Real_line">real line</a>.</p>
<h2>If-let</h2>
<p>Avoid <code>if let ... { } else { }</code> construct, use <code>match</code> instead.</p>
<pre class="language-rust"><a-c>// GOOD</a-c>
<a-k>match</a-k> ctx<a-p>.</a-p><a-pr>expected_type</a-pr><a-p>.</a-p><a-f>as_ref</a-f><a-p>()</a-p> <a-p>{</a-p>
    <a-cr>Some</a-cr><a-p>(</a-p>expected_type<a-p>)</a-p> =&gt; completion_ty == expected_type &amp;&amp; !expected_type<a-p>.</a-p><a-f>is_unit</a-f><a-p>(),</a-p>
    <a-cr>None</a-cr> =&gt; <a-co>false</a-co><a-p>,</a-p>
<a-p>}</a-p>

<a-c>// BAD</a-c>
<a-k>if</a-k> <a-k>let</a-k> <a-cr>Some</a-cr><a-p>(</a-p>expected_type<a-p>)</a-p> = ctx<a-p>.</a-p><a-pr>expected_type</a-pr><a-p>.</a-p><a-f>as_ref</a-f><a-p>()</a-p> <a-p>{</a-p>
    completion_ty == expected_type &amp;&amp; !expected_type<a-p>.</a-p><a-f>is_unit</a-f><a-p>()</a-p>
<a-p>}</a-p> <a-k>else</a-k> <a-p>{</a-p>
    <a-co>false</a-co>
<a-p>}</a-p></pre>
<p><strong>Rationale:</strong> <code>match</code> is almost always more compact.
The <code>else</code> branch can get a more precise pattern: <code>None</code> or <code>Err(_)</code> instead of <code>_</code>.</p>
<h2>Match Ergonomics</h2>
<p>Don't use the <code>ref</code> keyword.</p>
<p><strong>Rationale:</strong> consistency &amp; simplicity.
<code>ref</code> was required before <a href="https://github.com/rust-lang/rfcs/blob/master/text/2005-match-ergonomics.md">match ergonomics</a>.
Today, it is redundant.
Between <code>ref</code> and mach ergonomics, the latter is more ergonomic in most cases, and is simpler (does not require a keyword).</p>
<h2>Empty Match Arms</h2>
<p>Use <code>=&gt; (),</code> when a match arm is intentionally empty:</p>
<pre class="language-rust"><a-c>// GOOD</a-c>
<a-k>match</a-k> result <a-p>{</a-p>
    <a-cr>Ok</a-cr><a-p>(</a-p>_<a-p>)</a-p> =&gt; <a-p>(),</a-p>
    <a-cr>Err</a-cr><a-p>(</a-p>err<a-p>)</a-p> =&gt; <a-m>error!</a-m><a-p>(</a-p><a-s>&quot;{}&quot;</a-s><a-p>,</a-p> err<a-p>),</a-p>
<a-p>}</a-p>

<a-c>// BAD</a-c>
<a-k>match</a-k> result <a-p>{</a-p>
    <a-cr>Ok</a-cr><a-p>(</a-p>_<a-p>)</a-p> =&gt; <a-p>{}</a-p>
    <a-cr>Err</a-cr><a-p>(</a-p>err<a-p>)</a-p> =&gt; <a-m>error!</a-m><a-p>(</a-p><a-s>&quot;{}&quot;</a-s><a-p>,</a-p> err<a-p>),</a-p>
<a-p>}</a-p></pre>
<p><strong>Rationale:</strong> consistency.</p>
<h2>Functional Combinators</h2>
<p>Use high order monadic combinators like <code>map</code>, <code>then</code> when they are a natural choice; don't bend the code to fit into some combinator.
If writing a chain of combinators creates friction, replace them with control flow constructs: <code>for</code>, <code>if</code>, <code>match</code>.
Mostly avoid <code>bool::then</code> and <code>Option::filter</code>.</p>
<pre class="language-rust"><a-c>// GOOD</a-c>
<a-k>if</a-k> !x<a-p>.</a-p><a-f>cond</a-f><a-p>()</a-p> <a-p>{</a-p>
    <a-k>return</a-k> <a-cr>None</a-cr><a-p>;</a-p>
<a-p>}</a-p>
<a-f>Some</a-f><a-p>(</a-p>x<a-p>)</a-p>

<a-c>// BAD</a-c>
<a-cr>Some</a-cr><a-p>(</a-p>x<a-p>).</a-p><a-f>filter</a-f><a-p>(</a-p>|it| it<a-p>.</a-p><a-f>cond</a-f><a-p>())</a-p></pre>
<p>This rule is more "soft" then others, and boils down mostly to taste.
The guiding principle behind this rule is that code should be dense in computation, and sparse in the number of expressions per line.
The second example contains <em>less</em> computation -- the <code>filter</code> function is an indirection for <code>if</code>, it doesn't do any useful work by itself.
At the same time, it is more crowded -- it takes more time to visually scan it.</p>
<p><strong>Rationale:</strong> consistency, playing to language's strengths.
Rust has first-class support for imperative control flow constructs like <code>for</code> and <code>if</code>, while functions are less first-class due to lack of universal function type, currying, and non-first-class effects (<code>?</code>, <code>.await</code>).</p>
<h2>Turbofish</h2>
<p>Prefer type ascription over the turbofish.
When ascribing types, avoid <code>_</code></p>
<pre class="language-rust"><a-c>// GOOD</a-c>
<a-k>let</a-k> mutable<a-p>:</a-p> <a-t>Vec</a-t><a-p>&lt;</a-p><a-t>T</a-t><a-p>&gt;</a-p> = old<a-p>.</a-p><a-f>into_iter</a-f><a-p>().</a-p><a-f>map</a-f><a-p>(</a-p>|it| builder<a-p>.</a-p><a-f>make_mut</a-f><a-p>(</a-p>it<a-p>)).</a-p><a-f>collect</a-f><a-p>();</a-p>

<a-c>// BAD</a-c>
<a-k>let</a-k> mutable<a-p>:</a-p> <a-t>Vec</a-t><a-p>&lt;</a-p><a-t>_</a-t><a-p>&gt;</a-p> = old<a-p>.</a-p><a-f>into_iter</a-f><a-p>().</a-p><a-f>map</a-f><a-p>(</a-p>|it| builder<a-p>.</a-p><a-f>make_mut</a-f><a-p>(</a-p>it<a-p>)).</a-p><a-f>collect</a-f><a-p>();</a-p>

<a-c>// BAD</a-c>
<a-k>let</a-k> mutable = old<a-p>.</a-p><a-f>into_iter</a-f><a-p>().</a-p><a-f>map</a-f><a-p>(</a-p>|it| builder<a-p>.</a-p><a-f>make_mut</a-f><a-p>(</a-p>it<a-p>)).</a-p><a-f>collect</a-f><a-p>::&lt;</a-p><a-t>Vec</a-t><a-p>&lt;</a-p><a-t>_</a-t><a-p>&gt;&gt;();</a-p></pre>
<p><strong>Rationale:</strong> consistency, readability.
If compiler struggles to infer the type, the human would as well.
Having the result type specified up-front helps with understanding what the chain of iterator methods is doing.</p>
<h2>Helper Functions</h2>
<p>Avoid creating single-use helper functions:</p>
<pre class="language-rust"><a-c>// GOOD</a-c>
<a-k>let</a-k> buf = <a-p>{</a-p>
    <a-k>let</a-k> <a-k>mut</a-k> buf = <a-f>get_empty_buf</a-f><a-p>(</a-p><a-o>&amp;</a-o><a-k>mut</a-k> arena<a-p>);</a-p>
    buf<a-p>.</a-p><a-f>add_item</a-f><a-p>(</a-p>item<a-p>);</a-p>
    buf
<a-p>};</a-p>

<a-c>// BAD</a-c>
<a-k>let</a-k> buf = <a-f>prepare_buf</a-f><a-p>(</a-p><a-o>&amp;</a-o><a-k>mut</a-k> arena<a-p>,</a-p> item<a-p>);</a-p>

..<a-p>.</a-p>

fn <a-f>prepare_buf</a-f><a-p>(</a-p>arena<a-p>:</a-p> <a-o>&amp;</a-o>mut <a-cr>Arena</a-cr><a-p>,</a-p> item<a-p>:</a-p> <a-cr>Item</a-cr><a-p>)</a-p> -&gt; <a-cr>ItemBuf</a-cr> <a-p>{</a-p>
    let mut res = <a-f>get_empty_buf</a-f><a-p>(</a-p><a-o>&amp;</a-o><a-k>mut</a-k> arena<a-p>);</a-p>
    res<a-p>.</a-p><a-f>add_item</a-f><a-p>(</a-p>item<a-p>);</a-p>
    res
<a-p>}</a-p></pre>
<p>Exception: if you want to make use of <code>return</code> or <code>?</code>.</p>
<p><strong>Rationale:</strong> single-use functions change frequently, adding or removing parameters adds churn.
A block serves just as well to delineate a bit of logic, but has access to all the context.
Re-using originally single-purpose function often leads to bad coupling.</p>
<h2>Local Helper Functions</h2>
<p>Put nested helper functions at the end of the enclosing functions
(this requires using return statement).
Don't nest more than one level deep.</p>
<pre class="language-rust"><a-c>// GOOD</a-c>
<a-k>fn</a-k> <a-f>dfs</a-f><a-p>(</a-p><a-v>graph</a-v><a-p>:</a-p> <a-o>&amp;</a-o><a-t>Graph</a-t><a-p>,</a-p> <a-v>v</a-v><a-p>:</a-p> <a-t>Vertex</a-t><a-p>)</a-p> -&gt; <a-t>usize</a-t> <a-p>{</a-p>
    <a-k>let</a-k> <a-k>mut</a-k> visited = <a-t>FxHashSet</a-t><a-p>::</a-p><a-f>default</a-f><a-p>();</a-p>
    <a-k>return</a-k> <a-f>go</a-f><a-p>(</a-p>graph<a-p>,</a-p> <a-o>&amp;</a-o><a-k>mut</a-k> visited<a-p>,</a-p> v<a-p>);</a-p>

    <a-k>fn</a-k> <a-f>go</a-f><a-p>(</a-p><a-v>graph</a-v><a-p>:</a-p> <a-o>&amp;</a-o><a-t>Graph</a-t><a-p>,</a-p> <a-v>visited</a-v><a-p>:</a-p> <a-o>&amp;</a-o><a-k>mut</a-k> <a-t>FxHashSet</a-t><a-p>&lt;</a-p><a-t>Vertex</a-t><a-p>&gt;,</a-p> <a-v>v</a-v><a-p>:</a-p> <a-t>usize</a-t><a-p>)</a-p> -&gt; <a-t>usize</a-t> <a-p>{</a-p>
        ..<a-p>.</a-p><a-pr>
    </a-pr><a-p>}</a-p><a-pr>
</a-pr><a-p>}</a-p><a-pr>

</a-pr><a-c>// BAD</a-c><a-pr>
</a-pr><a-k>fn</a-k><a-pr> </a-pr><a-f>dfs</a-f><a-p>(</a-p><a-v>graph</a-v><a-p>:</a-p><a-pr> </a-pr><a-o>&amp;</a-o><a-t>Graph</a-t><a-p>,</a-p><a-pr> </a-pr><a-v>v</a-v><a-p>:</a-p><a-pr> </a-pr><a-t>Vertex</a-t><a-p>)</a-p><a-pr> -&gt; </a-pr><a-t>usize</a-t><a-pr> </a-pr><a-p>{</a-p><a-pr>
    </a-pr><a-k>fn</a-k><a-pr> </a-pr><a-f>go</a-f><a-p>(</a-p><a-v>graph</a-v><a-p>:</a-p><a-pr> </a-pr><a-o>&amp;</a-o><a-t>Graph</a-t><a-p>,</a-p><a-pr> </a-pr><a-v>visited</a-v><a-p>:</a-p><a-pr> </a-pr><a-o>&amp;</a-o><a-k>mut</a-k><a-pr> </a-pr><a-t>FxHashSet</a-t><a-p>&lt;</a-p><a-t>Vertex</a-t><a-p>&gt;,</a-p><a-pr> </a-pr><a-v>v</a-v><a-p>:</a-p><a-pr> </a-pr><a-t>usize</a-t><a-p>)</a-p><a-pr> -&gt; </a-pr><a-t>usize</a-t><a-pr> </a-pr><a-p>{</a-p><a-pr>
        ..</a-pr><a-p>.</a-p><a-pr>
    </a-pr><a-p>}</a-p><a-pr>

    </a-pr><a-k>let</a-k><a-pr> </a-pr><a-k>mut</a-k><a-pr> visited = </a-pr><a-t>FxHashSet</a-t><a-p>::</a-p><a-f>default</a-f><a-p>();</a-p><a-pr>
    </a-pr><a-f>go</a-f><a-p>(</a-p><a-pr>graph</a-pr><a-p>,</a-p><a-pr> </a-pr><a-o>&amp;</a-o><a-k>mut</a-k><a-pr> visited</a-pr><a-p>,</a-p><a-pr> v</a-pr><a-p>)</a-p><a-pr>
</a-pr><a-p>}</a-p></pre>
<p><strong>Rationale:</strong> consistency, improved top-down readability.</p>
<h2>Helper Variables</h2>
<p>Introduce helper variables freely, especially for multiline conditions:</p>
<pre class="language-rust"><a-c>// GOOD</a-c>
<a-k>let</a-k> rustfmt_not_installed =
    captured_stderr<a-p>.</a-p><a-f>contains</a-f><a-p>(</a-p><a-s>&quot;not installed&quot;</a-s><a-p>)</a-p> || captured_stderr<a-p>.</a-p><a-f>contains</a-f><a-p>(</a-p><a-s>&quot;not available&quot;</a-s><a-p>);</a-p>

<a-k>match</a-k> output<a-p>.</a-p><a-pr>status</a-pr><a-p>.</a-p><a-f>code</a-f><a-p>()</a-p> <a-p>{</a-p>
    <a-cr>Some</a-cr><a-p>(</a-p><a-co>1</a-co><a-p>)</a-p> <a-k>if</a-k> !rustfmt_not_installed =&gt; <a-f>Ok</a-f><a-p>(</a-p><a-cr>None</a-cr><a-p>),</a-p>
    _ =&gt; <a-f>Err</a-f><a-p>(</a-p><a-m>format_err!</a-m><a-p>(</a-p><a-s>&quot;rustfmt failed:\n{}&quot;</a-s><a-p>,</a-p> captured_stderr<a-p>)),</a-p>
<a-p>};</a-p>

<a-c>// BAD</a-c>
<a-k>match</a-k> output<a-p>.</a-p><a-pr>status</a-pr><a-p>.</a-p><a-f>code</a-f><a-p>()</a-p> <a-p>{</a-p>
    <a-cr>Some</a-cr><a-p>(</a-p><a-co>1</a-co><a-p>)</a-p>
        <a-k>if</a-k> !captured_stderr<a-p>.</a-p><a-f>contains</a-f><a-p>(</a-p><a-s>&quot;not installed&quot;</a-s><a-p>)</a-p>
           &amp;&amp; !captured_stderr<a-p>.</a-p><a-f>contains</a-f><a-p>(</a-p><a-s>&quot;not available&quot;</a-s><a-p>)</a-p> =&gt; <a-f>Ok</a-f><a-p>(</a-p><a-cr>None</a-cr><a-p>),</a-p>
    _ =&gt; <a-f>Err</a-f><a-p>(</a-p><a-m>format_err!</a-m><a-p>(</a-p><a-s>&quot;rustfmt failed:\n{}&quot;</a-s><a-p>,</a-p> captured_stderr<a-p>)),</a-p>
<a-p>};</a-p></pre>
<p><strong>Rationale:</strong> Like blocks, single-use variables are a cognitively cheap abstraction, as they have access to all the context.
Extra variables help during debugging, they make it easy to print/view important intermediate results.
Giving a name to a condition inside an <code>if</code> expression often improves clarity and leads to nicely formatted code.</p>
<h2>Token names</h2>
<p>Use <code>T![foo]</code> instead of <code>SyntaxKind::FOO_KW</code>.</p>
<pre class="language-rust"><a-c>// GOOD</a-c>
<a-k>match</a-k> p<a-p>.</a-p><a-f>current</a-f><a-p>()</a-p> <a-p>{</a-p>
    <a-m>T!</a-m><a-p>[</a-p><a-co>true</a-co><a-p>]</a-p> | <a-m>T!</a-m><a-p>[</a-p><a-co>false</a-co><a-p>]</a-p> =&gt; <a-co>true</a-co><a-p>,</a-p>
    _ =&gt; <a-co>false</a-co><a-p>,</a-p>
<a-p>}</a-p>

<a-c>// BAD</a-c>

<a-k>match</a-k> p<a-p>.</a-p><a-f>current</a-f><a-p>()</a-p> <a-p>{</a-p>
    <a-t>SyntaxKind</a-t><a-p>::</a-p><a-cr>TRUE_KW</a-cr> | <a-t>SyntaxKind</a-t><a-p>::</a-p><a-cr>FALSE_KW</a-cr> =&gt; <a-co>true</a-co><a-p>,</a-p>
    _ =&gt; <a-co>false</a-co><a-p>,</a-p>
<a-p>}</a-p></pre>
<p><strong>Rationale:</strong> The macro uses the familiar Rust syntax, avoiding ambiguities like "is this a brace or bracket?".</p>
<h2>Documentation</h2>
<p>Style inline code comments as proper sentences.
Start with a capital letter, end with a dot.</p>
<pre class="language-rust"><a-c>// GOOD</a-c>

<a-c>// Only simple single segment paths are allowed.</a-c>
<a-t>MergeBehavior</a-t><a-p>::</a-p><a-cr>Last</a-cr> =&gt; <a-p>{</a-p>
    tree<a-p>.</a-p><a-f>use_tree_list</a-f><a-p>().</a-p><a-f>is_none</a-f><a-p>()</a-p> &amp;&amp; tree<a-p>.</a-p><a-f>path</a-f><a-p>().</a-p><a-f>map</a-f><a-p>(</a-p>path_len<a-p>)</a-p> &lt;= <a-f>Some</a-f><a-p>(</a-p><a-co>1</a-co><a-p>)</a-p>
<a-p>}</a-p>

<a-c>// BAD</a-c>

<a-c>// only simple single segment paths are allowed</a-c>
<a-t>MergeBehavior</a-t><a-p>::</a-p><a-cr>Last</a-cr> =&gt; <a-p>{</a-p>
    tree<a-p>.</a-p><a-f>use_tree_list</a-f><a-p>().</a-p><a-f>is_none</a-f><a-p>()</a-p> &amp;&amp; tree<a-p>.</a-p><a-f>path</a-f><a-p>().</a-p><a-f>map</a-f><a-p>(</a-p>path_len<a-p>)</a-p> &lt;= <a-f>Some</a-f><a-p>(</a-p><a-co>1</a-co><a-p>)</a-p>
<a-p>}</a-p></pre>
<p><strong>Rationale:</strong> writing a sentence (or maybe even a paragraph) rather just "a comment" creates a more appropriate frame of mind.
It tricks you into writing down more of the context you keep in your head while coding.</p>
<p>For <code>.md</code> and <code>.adoc</code> files, prefer a sentence-per-line format, don't wrap lines.
If the line is too long, you want to split the sentence in two :-)</p>
<p><strong>Rationale:</strong> much easier to edit the text and read the diff, see <a href="https://asciidoctor.org/docs/asciidoc-recommended-practices/#one-sentence-per-line">this link</a>.</p>
</section><div class="code-panel"><pre class="code src language-markdown"><span class="code-line"><a class="ln" id="L1" href="#L1">1</a><span class="code-text">Our approach to &quot;clean code&quot; is two-fold:</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2" href="#L2">2</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L3" href="#L3">3</a><span class="code-text"><a-p>* </a-p>We generally don&#39;t block PRs on style changes.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L4" href="#L4">4</a><span class="code-text"><a-p>* </a-p>At the same time, all code in rust-analyzer is constantly refactored.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L5" href="#L5">5</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L6" href="#L6">6</a><span class="code-text"><a-p>It is explicitly OK for a reviewer to flag only some nits in the PR, and then send a follow-up cleanup PR for things which are easier to explain by example, cc-ing the original author.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L7" href="#L7">7</a><span class="code-text"><a-p>Sending small cleanup PRs (like renaming a single local variable) is encouraged.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L8" href="#L8">8</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L9" href="#L9">9</a><span class="code-text"><a-p>When reviewing pull requests prefer extending this document to leaving</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L10" href="#L10">10</a><span class="code-text"><a-p>non-reusable comments on the pull request itself.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L11" href="#L11">11</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L12" href="#L12">12</a><span class="code-text"><a-p># </a-p><a-tt>General</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L13" href="#L13">13</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L14" href="#L14">14</a><span class="code-text"><a-p>## </a-p><a-tt>Scale of Changes</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L15" href="#L15">15</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L16" href="#L16">16</a><span class="code-text"><a-p>Everyone knows that it&#39;s better to send small &amp; focused pull requests.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L17" href="#L17">17</a><span class="code-text"><a-p>The problem is, sometimes you *have* to, eg, rewrite the whole compiler, and that just doesn&#39;t fit into a set of isolated PRs.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L18" href="#L18">18</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L19" href="#L19">19</a><span class="code-text"><a-p>The main things to keep an eye on are the boundaries between various components.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L20" href="#L20">20</a><span class="code-text"><a-p>There are three kinds of changes:</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L21" href="#L21">21</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L22" href="#L22">22</a><span class="code-text"><a-p>1. Internals of a single component are changed.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L23" href="#L23">23</a><span class="code-text"><a-p>   Specifically, you don&#39;t change any `pub` items.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L24" href="#L24">24</a><span class="code-text"><a-p>   A good example here would be an addition of a new assist.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L25" href="#L25">25</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L26" href="#L26">26</a><span class="code-text"><a-p>2. API of a component is expanded.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L27" href="#L27">27</a><span class="code-text"><a-p>   Specifically, you add a new `pub` function which wasn&#39;t there before.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L28" href="#L28">28</a><span class="code-text"><a-p>   A good example here would be expansion of assist API, for example, to implement lazy assists or assists groups.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L29" href="#L29">29</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L30" href="#L30">30</a><span class="code-text"><a-p>3. A new dependency between components is introduced.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L31" href="#L31">31</a><span class="code-text"><a-p>   Specifically, you add a `pub use` reexport from another crate or you add a new line to the `[dependencies]` section of `Cargo.toml`.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L32" href="#L32">32</a><span class="code-text"><a-p>   A good example here would be adding reference search capability to the assists crates.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L33" href="#L33">33</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L34" href="#L34">34</a><span class="code-text"><a-p>For the first group, the change is generally merged as long as:</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L35" href="#L35">35</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L36" href="#L36">36</a><span class="code-text"><a-p>* it works for the happy case,</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L37" href="#L37">37</a><span class="code-text"><a-p>* it has tests,</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L38" href="#L38">38</a><span class="code-text"><a-p>* it doesn&#39;t panic for the unhappy case.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L39" href="#L39">39</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L40" href="#L40">40</a><span class="code-text"><a-p>For the second group, the change would be subjected to quite a bit of scrutiny and iteration.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L41" href="#L41">41</a><span class="code-text"><a-p>The new API needs to be right (or at least easy to change later).</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L42" href="#L42">42</a><span class="code-text"><a-p>The actual implementation doesn&#39;t matter that much.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L43" href="#L43">43</a><span class="code-text"><a-p>It&#39;s very important to minimize the amount of changed lines of code for changes of the second kind.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L44" href="#L44">44</a><span class="code-text"><a-p>Often, you start doing a change of the first kind, only to realize that you need to elevate to a change of the second kind.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L45" href="#L45">45</a><span class="code-text"><a-p>In this case, we&#39;ll probably ask you to split API changes into a separate PR.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L46" href="#L46">46</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L47" href="#L47">47</a><span class="code-text"><a-p>Changes of the third group should be pretty rare, so we don&#39;t specify any specific process for them.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L48" href="#L48">48</a><span class="code-text"><a-p>That said, adding an innocent-looking `pub use` is a very simple way to break encapsulation, keep an eye on it!</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L49" href="#L49">49</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L50" href="#L50">50</a><span class="code-text"><a-p>Note: if you enjoyed this abstract hand-waving about boundaries, you might appreciate</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L51" href="#L51">51</a><span class="code-text"><a-p>https://www.tedinski.com/2018/02/06/system-boundaries.html</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L52" href="#L52">52</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L53" href="#L53">53</a><span class="code-text"><a-p>## </a-p><a-tt>Crates.io Dependencies</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L54" href="#L54">54</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L55" href="#L55">55</a><span class="code-text"><a-p>We try to be very conservative with usage of crates.io dependencies.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L56" href="#L56">56</a><span class="code-text"><a-p>Don&#39;t use small &quot;helper&quot; crates (exception: `itertools` and `either` are allowed).</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L57" href="#L57">57</a><span class="code-text"><a-p>If there&#39;s some general reusable bit of code you need, consider adding it to the `stdx` crate.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L58" href="#L58">58</a><span class="code-text"><a-p>A useful exercise is to read Cargo.lock and see if some *transitive* dependencies do not make sense for rust-analyzer.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L59" href="#L59">59</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L60" href="#L60">60</a><span class="code-text"><a-p>**Rationale:** keep compile times low, create ecosystem pressure for faster compiles, reduce the number of things which might break.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L61" href="#L61">61</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L62" href="#L62">62</a><span class="code-text"><a-p>## </a-p><a-tt>Commit Style</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L63" href="#L63">63</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L64" href="#L64">64</a><span class="code-text"><a-p>We don&#39;t have specific rules around git history hygiene.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L65" href="#L65">65</a><span class="code-text"><a-p>Maintaining clean git history is strongly encouraged, but not enforced.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L66" href="#L66">66</a><span class="code-text"><a-p>Use rebase workflow, it&#39;s OK to rewrite history during PR review process.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L67" href="#L67">67</a><span class="code-text"><a-p>After you are happy with the state of the code, please use [interactive rebase](https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History) to squash fixup commits.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L68" href="#L68">68</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L69" href="#L69">69</a><span class="code-text"><a-p>Avoid @mentioning people in commit messages and pull request descriptions(they are added to commit message by bors).</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L70" href="#L70">70</a><span class="code-text"><a-p>Such messages create a lot of duplicate notification traffic during rebases.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L71" href="#L71">71</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L72" href="#L72">72</a><span class="code-text"><a-p>If possible, write Pull Request titles and descriptions from the user&#39;s perspective:</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L73" href="#L73">73</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L74" href="#L74">74</a><span class="code-text"><a-p>```</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L75" href="#L75">75</a><span class="code-text"><a-p># GOOD</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L76" href="#L76">76</a><span class="code-text"><a-p>Make goto definition work inside macros</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L77" href="#L77">77</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L78" href="#L78">78</a><span class="code-text"><a-p># BAD</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L79" href="#L79">79</a><span class="code-text"><a-p>Use original span for FileId</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L80" href="#L80">80</a><span class="code-text"><a-p>```</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L81" href="#L81">81</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L82" href="#L82">82</a><span class="code-text"><a-p>This makes it easier to prepare a changelog.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L83" href="#L83">83</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L84" href="#L84">84</a><span class="code-text"><a-p>If the change adds a new user-visible functionality, consider recording a GIF with [peek](https://github.com/phw/peek) and pasting it into the PR description.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L85" href="#L85">85</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L86" href="#L86">86</a><span class="code-text"><a-p>To make writing the release notes easier, you can mark a pull request as a feature, fix, internal change, or minor.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L87" href="#L87">87</a><span class="code-text"><a-p>Minor changes are excluded from the release notes, while the other types are distributed in their corresponding sections.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L88" href="#L88">88</a><span class="code-text"><a-p>There are two ways to mark this:</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L89" href="#L89">89</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L90" href="#L90">90</a><span class="code-text"><a-p>* use a `feat: `, `feature: `, `fix: `, `internal: ` or `minor: ` prefix in the PR title</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L91" href="#L91">91</a><span class="code-text"><a-p>* write `changelog [feature|fix|internal|skip] [description]` in a comment or in the PR description; the description is optional, and will replace the title if included.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L92" href="#L92">92</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L93" href="#L93">93</a><span class="code-text"><a-p>These comments don&#39;t have to be added by the PR author.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L94" href="#L94">94</a><span class="code-text"><a-p>Editing a comment or the PR description or title is also fine, as long as it happens before the release.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L95" href="#L95">95</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L96" href="#L96">96</a><span class="code-text"><a-p>**Rationale:** clean history is potentially useful, but rarely used.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L97" href="#L97">97</a><span class="code-text"><a-p>But many users read changelogs.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L98" href="#L98">98</a><span class="code-text"><a-p>Including a description and GIF suitable for the changelog means less work for the maintainers on the release day.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L99" href="#L99">99</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L100" href="#L100">100</a><span class="code-text"><a-p>## </a-p><a-tt>Clippy</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L101" href="#L101">101</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L102" href="#L102">102</a><span class="code-text"><a-p>We don&#39;t enforce Clippy.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L103" href="#L103">103</a><span class="code-text"><a-p>A number of default lints have high false positive rate.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L104" href="#L104">104</a><span class="code-text"><a-p>Selectively patching false-positives with `allow(clippy)` is considered worse than not using Clippy at all.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L105" href="#L105">105</a><span class="code-text"><a-p>There&#39;s a `cargo lint` command which runs a subset of low-FPR lints.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L106" href="#L106">106</a><span class="code-text"><a-p>Careful tweaking of `lint` is welcome.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L107" href="#L107">107</a><span class="code-text"><a-p>Of course, applying Clippy suggestions is welcome as long as they indeed improve the code.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L108" href="#L108">108</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L109" href="#L109">109</a><span class="code-text"><a-p>**Rationale:** see [rust-lang/clippy#5537](https://github.com/rust-lang/rust-clippy/issues/5537).</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L110" href="#L110">110</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L111" href="#L111">111</a><span class="code-text"><a-p># </a-p><a-tt>Code</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L112" href="#L112">112</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L113" href="#L113">113</a><span class="code-text"><a-p>## </a-p><a-tt>Minimal Tests</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L114" href="#L114">114</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L115" href="#L115">115</a><span class="code-text"><a-p>Most tests in rust-analyzer start with a snippet of Rust code.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L116" href="#L116">116</a><span class="code-text"><a-p>These snippets should be minimal -- if you copy-paste a snippet of real code into the tests, make sure to remove everything which could be removed.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L117" href="#L117">117</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L118" href="#L118">118</a><span class="code-text"><a-p>It also makes sense to format snippets more compactly (for example, by placing enum definitions like `enum E { Foo, Bar }` on a single line),</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L119" href="#L119">119</a><span class="code-text"><a-p>as long as they are still readable.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L120" href="#L120">120</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L121" href="#L121">121</a><span class="code-text"><a-p>When using multiline fixtures, use unindented raw string literals:</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L122" href="#L122">122</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L123" href="#L123">123</a><span class="code-text"><a-p>```</a-p><a-tl>rust</a-tl></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L124" href="#L124">124</a><span class="code-text"><a-p>    </a-p><a-at>#</a-at><a-p>[</a-p><a-at>test</a-at><a-p>]</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L125" href="#L125">125</a><span class="code-text"><a-p>    </a-p><a-k>fn</a-k><a-p> </a-p><a-f>inline_field_shorthand</a-f><a-p>() {</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L126" href="#L126">126</a><span class="code-text"><a-p>        </a-p><a-f>check_assist</a-f><a-p>(</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L127" href="#L127">127</a><span class="code-text"><a-p>            inline_local_variable,</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L128" href="#L128">128</a><span class="code-text"><a-p>            </a-p><a-s>r#&quot;</a-s></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L129" href="#L129">129</a><span class="code-text"><a-p>struct S { foo: i32}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L130" href="#L130">130</a><span class="code-text"><a-p>fn main() {</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L131" href="#L131">131</a><span class="code-text"><a-p>    let $0foo = 92;</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L132" href="#L132">132</a><span class="code-text"><a-p>    S { foo }</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L133" href="#L133">133</a><span class="code-text"><a-p>}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L134" href="#L134">134</a><span class="code-text"><a-p>&quot;#,</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L135" href="#L135">135</a><span class="code-text"><a-p>            </a-p><a-s>r#&quot;</a-s></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L136" href="#L136">136</a><span class="code-text"><a-p>struct S { foo: i32}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L137" href="#L137">137</a><span class="code-text"><a-p>fn main() {</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L138" href="#L138">138</a><span class="code-text"><a-p>    S { foo: 92 }</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L139" href="#L139">139</a><span class="code-text"><a-p>}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L140" href="#L140">140</a><span class="code-text"><a-p>&quot;#,</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L141" href="#L141">141</a><span class="code-text"><a-p>        );</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L142" href="#L142">142</a><span class="code-text"><a-p>    }</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L143" href="#L143">143</a><span class="code-text"><a-p>```</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L144" href="#L144">144</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L145" href="#L145">145</a><span class="code-text"><a-p>**Rationale:**</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L146" href="#L146">146</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L147" href="#L147">147</a><span class="code-text"><a-p>There are many benefits to this:</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L148" href="#L148">148</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L149" href="#L149">149</a><span class="code-text"><a-p>* less to read or to scroll past</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L150" href="#L150">150</a><span class="code-text"><a-p>* easier to understand what exactly is tested</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L151" href="#L151">151</a><span class="code-text"><a-p>* less stuff printed during printf-debugging</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L152" href="#L152">152</a><span class="code-text"><a-p>* less time to run test</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L153" href="#L153">153</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L154" href="#L154">154</a><span class="code-text"><a-p>Formatting ensures that you can use your editor&#39;s &quot;number of selected characters&quot; feature to correlate offsets with test&#39;s source code.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L155" href="#L155">155</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L156" href="#L156">156</a><span class="code-text"><a-p>## </a-p><a-tt>Marked Tests</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L157" href="#L157">157</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L158" href="#L158">158</a><span class="code-text"><a-p>Use</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L159" href="#L159">159</a><span class="code-text"><a-p>[`cov_mark::hit! / cov_mark::check!`](https://github.com/matklad/cov-mark)</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L160" href="#L160">160</a><span class="code-text"><a-p>when testing specific conditions.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L161" href="#L161">161</a><span class="code-text"><a-p>Do not place several marks into a single test or condition.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L162" href="#L162">162</a><span class="code-text"><a-p>Do not reuse marks between several tests.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L163" href="#L163">163</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L164" href="#L164">164</a><span class="code-text"><a-p>**Rationale:** marks provide an easy way to find the canonical test for each bit of code.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L165" href="#L165">165</a><span class="code-text"><a-p>This makes it much easier to understand.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L166" href="#L166">166</a><span class="code-text"><a-p>More than one mark per test / code branch doesn&#39;t add significantly to understanding.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L167" href="#L167">167</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L168" href="#L168">168</a><span class="code-text"><a-p>## </a-p><a-tt>`#[should_panic]`</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L169" href="#L169">169</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L170" href="#L170">170</a><span class="code-text"><a-p>Do not use `#[should_panic]` tests.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L171" href="#L171">171</a><span class="code-text"><a-p>Instead, explicitly check for `None`, `Err`, etc.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L172" href="#L172">172</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L173" href="#L173">173</a><span class="code-text"><a-p>**Rationale:** `#[should_panic]` is a tool for library authors to make sure that the API does not fail silently when misused.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L174" href="#L174">174</a><span class="code-text"><a-p>`rust-analyzer` is not a library, we don&#39;t need to test for API misuse, and we have to handle any user input without panics.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L175" href="#L175">175</a><span class="code-text"><a-p>Panic messages in the logs from the `#[should_panic]` tests are confusing.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L176" href="#L176">176</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L177" href="#L177">177</a><span class="code-text"><a-p>## </a-p><a-tt>`#[ignore]`</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L178" href="#L178">178</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L179" href="#L179">179</a><span class="code-text"><a-p>Do not `#[ignore]` tests.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L180" href="#L180">180</a><span class="code-text"><a-p>If the test currently does not work, assert the wrong behavior and add a fixme explaining why it is wrong.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L181" href="#L181">181</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L182" href="#L182">182</a><span class="code-text"><a-p>**Rationale:** noticing when the behavior is fixed, making sure that even the wrong behavior is acceptable (ie, not a panic).</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L183" href="#L183">183</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L184" href="#L184">184</a><span class="code-text"><a-p>## </a-p><a-tt>Function Preconditions</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L185" href="#L185">185</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L186" href="#L186">186</a><span class="code-text"><a-p>Express function preconditions in types and force the caller to provide them (rather than checking in callee):</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L187" href="#L187">187</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L188" href="#L188">188</a><span class="code-text"><a-p>```</a-p><a-tl>rust</a-tl></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L189" href="#L189">189</a><span class="code-text"><a-p>// GOOD</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L190" href="#L190">190</a><span class="code-text"><a-p>fn </a-p><a-f>frobnicate</a-f><a-p>(</a-p><a-v>walrus</a-v><a-p>: </a-p><a-t>Walrus</a-t><a-p>) {</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L191" href="#L191">191</a><span class="code-text"><a-p>    ...</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L192" href="#L192">192</a><span class="code-text"><a-p>}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L193" href="#L193">193</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L194" href="#L194">194</a><span class="code-text"><a-p>// BAD</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L195" href="#L195">195</a><span class="code-text"><a-p>fn </a-p><a-f>frobnicate</a-f><a-p>(</a-p><a-v>walrus</a-v><a-p>: </a-p><a-t>Option</a-t><a-p>&lt;</a-p><a-t>Walrus</a-t><a-p>&gt;) {</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L196" href="#L196">196</a><span class="code-text"><a-p>    </a-p><a-k>let</a-k><a-p> walrus = </a-p><a-k>match</a-k><a-p> walrus {</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L197" href="#L197">197</a><span class="code-text"><a-p>        </a-p><a-cr>Some</a-cr><a-p>(it) =&gt; it,</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L198" href="#L198">198</a><span class="code-text"><a-p>        </a-p><a-cr>None</a-cr><a-p> =&gt; </a-p><a-k>return</a-k><a-p>,</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L199" href="#L199">199</a><span class="code-text"><a-p>    };</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L200" href="#L200">200</a><span class="code-text"><a-p>    ...</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L201" href="#L201">201</a><span class="code-text"><a-p>}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L202" href="#L202">202</a><span class="code-text"><a-p>```</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L203" href="#L203">203</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L204" href="#L204">204</a><span class="code-text"><a-pr>**Rationale:** this makes control flow explicit at the call site.</a-pr></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L205" href="#L205">205</a><span class="code-text"><a-pr>Call-site has more context, it often happens that the precondition falls out naturally or can be bubbled up higher in the stack.</a-pr></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L206" href="#L206">206</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L207" href="#L207">207</a><span class="code-text"><a-pr>Avoid splitting precondition check and precondition use across functions:</a-pr></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L208" href="#L208">208</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L209" href="#L209">209</a><span class="code-text"><a-p>```</a-p><a-tl>rust</a-tl></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L210" href="#L210">210</a><span class="code-text"><a-p>// GOOD</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L211" href="#L211">211</a><span class="code-text"><a-p>fn </a-p><a-f>main</a-f><a-p>() {</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L212" href="#L212">212</a><span class="code-text"><a-p>    </a-p><a-k>let</a-k><a-p> s: </a-p><a-o>&amp;</a-o><a-t>str</a-t><a-p> = ...</a-p><a-pr>;</a-pr></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L213" href="#L213">213</a><span class="code-text"><a-p>    </a-p><a-k>if</a-k><a-p> </a-p><a-k>let</a-k><a-p> </a-p><a-cr>Some</a-cr><a-p>(contents) = </a-p><a-f>string_literal_contents</a-f><a-p>(s) {</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L214" href="#L214">214</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L215" href="#L215">215</a><span class="code-text"><a-p>    }</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L216" href="#L216">216</a><span class="code-text"><a-p>}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L217" href="#L217">217</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L218" href="#L218">218</a><span class="code-text"><a-p>fn </a-p><a-f>string_literal_contents</a-f><a-p>(</a-p><a-v>s</a-v><a-p>: </a-p><a-o>&amp;</a-o><a-t>str</a-t><a-p>) -&gt; </a-p><a-t>Option</a-t><a-p>&lt;</a-p><a-o>&amp;</a-o><a-t>str</a-t><a-p>&gt; {</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L219" href="#L219">219</a><span class="code-text"><a-p>    </a-p><a-k>if</a-k><a-p> s.</a-p><a-f>starts_with</a-f><a-p>(</a-p><a-s>&#39;&quot;&#39;</a-s><a-p>) &amp;&amp; s.</a-p><a-f>ends_with</a-f><a-p>(</a-p><a-s>&#39;&quot;&#39;</a-s><a-p>) {</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L220" href="#L220">220</a><span class="code-text"><a-p>        </a-p><a-f>Some</a-f><a-p>(</a-p><a-o>&amp;</a-o><a-p>s[</a-p><a-co>1</a-co><a-p>..s.</a-p><a-f>len</a-f><a-p>() - </a-p><a-co>1</a-co><a-p>])</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L221" href="#L221">221</a><span class="code-text"><a-p>    } </a-p><a-k>else</a-k><a-p> {</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L222" href="#L222">222</a><span class="code-text"><a-p>        </a-p><a-cr>None</a-cr></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L223" href="#L223">223</a><span class="code-text"><a-p>    }</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L224" href="#L224">224</a><span class="code-text"><a-p>}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L225" href="#L225">225</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L226" href="#L226">226</a><span class="code-text"><a-p>// BAD</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L227" href="#L227">227</a><span class="code-text"><a-p>fn </a-p><a-f>main</a-f><a-p>() {</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L228" href="#L228">228</a><span class="code-text"><a-p>    </a-p><a-k>let</a-k><a-p> s: </a-p><a-o>&amp;</a-o><a-t>str</a-t><a-p> = ...</a-p><a-pr>;</a-pr></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L229" href="#L229">229</a><span class="code-text"><a-p>    </a-p><a-k>if</a-k><a-p> </a-p><a-f>is_string_literal</a-f><a-p>(s) {</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L230" href="#L230">230</a><span class="code-text"><a-p>        </a-p><a-k>let</a-k><a-p> contents = </a-p><a-o>&amp;</a-o><a-p>s[</a-p><a-co>1</a-co><a-p>..s.</a-p><a-f>len</a-f><a-p>() - </a-p><a-co>1</a-co><a-p>];</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L231" href="#L231">231</a><span class="code-text"><a-p>    }</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L232" href="#L232">232</a><span class="code-text"><a-p>}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L233" href="#L233">233</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L234" href="#L234">234</a><span class="code-text"><a-p>fn </a-p><a-f>is_string_literal</a-f><a-p>(</a-p><a-v>s</a-v><a-p>: </a-p><a-o>&amp;</a-o><a-t>str</a-t><a-p>) -&gt; </a-p><a-t>bool</a-t><a-p> {</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L235" href="#L235">235</a><span class="code-text"><a-p>    s.</a-p><a-f>starts_with</a-f><a-p>(</a-p><a-s>&#39;&quot;&#39;</a-s><a-p>) &amp;&amp; s.</a-p><a-f>ends_with</a-f><a-p>(</a-p><a-s>&#39;&quot;&#39;</a-s><a-p>)</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L236" href="#L236">236</a><span class="code-text"><a-p>}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L237" href="#L237">237</a><span class="code-text"><a-p>```</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L238" href="#L238">238</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L239" href="#L239">239</a><span class="code-text"><a-p>In the &quot;Not as good&quot; version, the precondition that `1` is a valid char boundary is checked in `is_string_literal` and used in `foo`.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L240" href="#L240">240</a><span class="code-text"><a-p>In the &quot;Good&quot; version, the precondition check and usage are checked in the same block, and then encoded in the types.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L241" href="#L241">241</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L242" href="#L242">242</a><span class="code-text"><a-p>**Rationale:** non-local code properties degrade under change.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L243" href="#L243">243</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L244" href="#L244">244</a><span class="code-text"><a-p>When checking a boolean precondition, prefer `if !invariant` to `if negated_invariant`:</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L245" href="#L245">245</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L246" href="#L246">246</a><span class="code-text"><a-p>```</a-p><a-tl>rust</a-tl></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L247" href="#L247">247</a><span class="code-text"><a-p>// GOOD</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L248" href="#L248">248</a><span class="code-text"><a-p>if !(idx &lt; len) {</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L249" href="#L249">249</a><span class="code-text"><a-p>    </a-p><a-k>return</a-k><a-p> </a-p><a-cr>None</a-cr><a-p>;</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L250" href="#L250">250</a><span class="code-text"><a-p>}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L251" href="#L251">251</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L252" href="#L252">252</a><span class="code-text"><a-p>// BAD</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L253" href="#L253">253</a><span class="code-text"><a-p>if idx &gt;= len {</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L254" href="#L254">254</a><span class="code-text"><a-p>    </a-p><a-k>return</a-k><a-p> </a-p><a-cr>None</a-cr><a-p>;</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L255" href="#L255">255</a><span class="code-text"><a-p>}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L256" href="#L256">256</a><span class="code-text"><a-p>```</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L257" href="#L257">257</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L258" href="#L258">258</a><span class="code-text"><a-p>**Rationale:** it&#39;s useful to see the invariant relied upon by the rest of the function clearly spelled out.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L259" href="#L259">259</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L260" href="#L260">260</a><span class="code-text"><a-p>## </a-p><a-tt>Control Flow</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L261" href="#L261">261</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L262" href="#L262">262</a><span class="code-text"><a-p>As a special case of the previous rule, do not hide control flow inside functions, push it to the caller:</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L263" href="#L263">263</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L264" href="#L264">264</a><span class="code-text"><a-p>```</a-p><a-tl>rust</a-tl></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L265" href="#L265">265</a><span class="code-text"><a-p>// GOOD</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L266" href="#L266">266</a><span class="code-text"><a-p>if cond {</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L267" href="#L267">267</a><span class="code-text"><a-p>    </a-p><a-f>f</a-f><a-p>()</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L268" href="#L268">268</a><span class="code-text"><a-p>}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L269" href="#L269">269</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L270" href="#L270">270</a><span class="code-text"><a-p>// BAD</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L271" href="#L271">271</a><span class="code-text"><a-p>fn </a-p><a-f>f</a-f><a-p>() {</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L272" href="#L272">272</a><span class="code-text"><a-p>    </a-p><a-k>if</a-k><a-p> !cond {</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L273" href="#L273">273</a><span class="code-text"><a-p>        </a-p><a-k>return</a-k><a-p>;</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L274" href="#L274">274</a><span class="code-text"><a-p>    }</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L275" href="#L275">275</a><span class="code-text"><a-p>    ...</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L276" href="#L276">276</a><span class="code-text"><a-p>}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L277" href="#L277">277</a><span class="code-text"><a-p>```</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L278" href="#L278">278</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L279" href="#L279">279</a><span class="code-text"><a-p>## </a-p><a-tt>Assertions</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L280" href="#L280">280</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L281" href="#L281">281</a><span class="code-text"><a-p>Assert liberally.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L282" href="#L282">282</a><span class="code-text"><a-p>Prefer [`stdx::never!`](https://docs.rs/always-assert/0.1.2/always_assert/macro.never.html) to standard `assert!`.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L283" href="#L283">283</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L284" href="#L284">284</a><span class="code-text"><a-p>**Rationale:** See [cross cutting concern: error handling](https://github.com/rust-lang/rust-analyzer/blob/master/docs/dev/architecture.md#error-handling).</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L285" href="#L285">285</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L286" href="#L286">286</a><span class="code-text"><a-p>## </a-p><a-tt>Getters &amp; Setters</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L287" href="#L287">287</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L288" href="#L288">288</a><span class="code-text"><a-p>If a field can have any value without breaking invariants, make the field public.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L289" href="#L289">289</a><span class="code-text"><a-p>Conversely, if there is an invariant, document it, enforce it in the &quot;constructor&quot; function, make the field private, and provide a getter.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L290" href="#L290">290</a><span class="code-text"><a-p>Never provide setters.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L291" href="#L291">291</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L292" href="#L292">292</a><span class="code-text"><a-p>Getters should return borrowed data:</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L293" href="#L293">293</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L294" href="#L294">294</a><span class="code-text"><a-p>```</a-p><a-tl>rust</a-tl></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L295" href="#L295">295</a><span class="code-text"><a-p>struct </a-p><a-t>Person</a-t><a-p> {</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L296" href="#L296">296</a><span class="code-text"><a-p>    </a-p><a-c>// Invariant: never empty</a-c></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L297" href="#L297">297</a><span class="code-text"><a-p>    </a-p><a-pr>first_name</a-pr><a-p>: </a-p><a-t>String</a-t><a-p>,</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L298" href="#L298">298</a><span class="code-text"><a-p>    </a-p><a-pr>middle_name</a-pr><a-p>: </a-p><a-t>Option</a-t><a-p>&lt;</a-p><a-t>String</a-t><a-p>&gt;</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L299" href="#L299">299</a><span class="code-text"><a-p>}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L300" href="#L300">300</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L301" href="#L301">301</a><span class="code-text"><a-p>// GOOD</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L302" href="#L302">302</a><span class="code-text"><a-p>impl </a-p><a-t>Person</a-t><a-p> {</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L303" href="#L303">303</a><span class="code-text"><a-p>    </a-p><a-k>fn</a-k><a-p> </a-p><a-f>first_name</a-f><a-p>(</a-p><a-o>&amp;</a-o><a-v>self</a-v><a-p>) -&gt; </a-p><a-o>&amp;</a-o><a-t>str</a-t><a-p> { </a-p><a-v>self</a-v><a-p>.</a-p><a-pr>first_name</a-pr><a-p>.</a-p><a-f>as_str</a-f><a-p>() }</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L304" href="#L304">304</a><span class="code-text"><a-p>    </a-p><a-k>fn</a-k><a-p> </a-p><a-f>middle_name</a-f><a-p>(</a-p><a-o>&amp;</a-o><a-v>self</a-v><a-p>) -&gt; </a-p><a-t>Option</a-t><a-p>&lt;</a-p><a-o>&amp;</a-o><a-t>str</a-t><a-p>&gt; { </a-p><a-v>self</a-v><a-p>.</a-p><a-pr>middle_name</a-pr><a-p>.</a-p><a-f>as_ref</a-f><a-p>() }</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L305" href="#L305">305</a><span class="code-text"><a-p>}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L306" href="#L306">306</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L307" href="#L307">307</a><span class="code-text"><a-p>// BAD</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L308" href="#L308">308</a><span class="code-text"><a-p>impl </a-p><a-t>Person</a-t><a-p> {</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L309" href="#L309">309</a><span class="code-text"><a-p>    </a-p><a-k>fn</a-k><a-p> </a-p><a-f>first_name</a-f><a-p>(</a-p><a-o>&amp;</a-o><a-v>self</a-v><a-p>) -&gt; </a-p><a-t>String</a-t><a-p> { </a-p><a-v>self</a-v><a-p>.</a-p><a-pr>first_name</a-pr><a-p>.</a-p><a-f>clone</a-f><a-p>() }</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L310" href="#L310">310</a><span class="code-text"><a-p>    </a-p><a-k>fn</a-k><a-p> </a-p><a-f>middle_name</a-f><a-p>(</a-p><a-o>&amp;</a-o><a-v>self</a-v><a-p>) -&gt; </a-p><a-o>&amp;</a-o><a-t>Option</a-t><a-p>&lt;</a-p><a-t>String</a-t><a-p>&gt; { </a-p><a-o>&amp;</a-o><a-v>self</a-v><a-p>.</a-p><a-pr>middle_name</a-pr><a-p> }</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L311" href="#L311">311</a><span class="code-text"><a-p>}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L312" href="#L312">312</a><span class="code-text"><a-p>```</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L313" href="#L313">313</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L314" href="#L314">314</a><span class="code-text"><a-p>**Rationale:** we don&#39;t provide public API, it&#39;s cheaper to refactor than to pay getters rent.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L315" href="#L315">315</a><span class="code-text"><a-p>Non-local code properties degrade under change, privacy makes invariant local.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L316" href="#L316">316</a><span class="code-text"><a-p>Borrowed owned types (`&amp;String`) disclose irrelevant details about internal representation.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L317" href="#L317">317</a><span class="code-text"><a-p>Irrelevant (neither right nor wrong) things obscure correctness.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L318" href="#L318">318</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L319" href="#L319">319</a><span class="code-text"><a-p>## </a-p><a-tt>Useless Types</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L320" href="#L320">320</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L321" href="#L321">321</a><span class="code-text"><a-p>More generally, always prefer types on the left</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L322" href="#L322">322</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L323" href="#L323">323</a><span class="code-text"><a-p>```</a-p><a-tl>rust</a-tl></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L324" href="#L324">324</a><span class="code-text"><a-p>// GOOD      BAD</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L325" href="#L325">325</a><span class="code-text"><a-p>&amp;[</a-p><a-cr>T</a-cr><a-p>]         </a-p><a-o>&amp;</a-o><a-cr>Vec</a-cr><a-p>&lt;</a-p><a-cr>T</a-cr><a-p>&gt;</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L326" href="#L326">326</a><span class="code-text"><a-p>&amp;str         </a-p><a-o>&amp;</a-o><a-cr>String</a-cr></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L327" href="#L327">327</a><span class="code-text"><a-p>Option&lt;</a-p><a-o>&amp;</a-o><a-cr>T</a-cr><a-p>&gt;   </a-p><a-o>&amp;</a-o><a-cr>Option</a-cr><a-p>&lt;</a-p><a-cr>T</a-cr><a-p>&gt;</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L328" href="#L328">328</a><span class="code-text"><a-p>&amp;</a-p><a-cr>Path</a-cr><a-p>        </a-p><a-o>&amp;</a-o><a-cr>PathBuf</a-cr></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L329" href="#L329">329</a><span class="code-text"><a-p>```</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L330" href="#L330">330</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L331" href="#L331">331</a><span class="code-text"><a-p>**Rationale:** types on the left are strictly more general.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L332" href="#L332">332</a><span class="code-text"><a-p>Even when generality is not required, consistency is important.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L333" href="#L333">333</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L334" href="#L334">334</a><span class="code-text"><a-p>## </a-p><a-tt>Constructors</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L335" href="#L335">335</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L336" href="#L336">336</a><span class="code-text"><a-p>Prefer `Default` to zero-argument `new` function.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L337" href="#L337">337</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L338" href="#L338">338</a><span class="code-text"><a-p>```</a-p><a-tl>rust</a-tl></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L339" href="#L339">339</a><span class="code-text"><a-p>// GOOD</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L340" href="#L340">340</a><span class="code-text"><a-p>#[derive(</a-p><a-cr>Default</a-cr><a-p>)]</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L341" href="#L341">341</a><span class="code-text"><a-p>struct </a-p><a-t>Foo</a-t><a-p> {</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L342" href="#L342">342</a><span class="code-text"><a-p>    </a-p><a-pr>bar</a-pr><a-p>: </a-p><a-t>Option</a-t><a-p>&lt;</a-p><a-t>Bar</a-t><a-p>&gt;</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L343" href="#L343">343</a><span class="code-text"><a-p>}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L344" href="#L344">344</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L345" href="#L345">345</a><span class="code-text"><a-p>// BAD</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L346" href="#L346">346</a><span class="code-text"><a-p>struct </a-p><a-t>Foo</a-t><a-p> {</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L347" href="#L347">347</a><span class="code-text"><a-p>    </a-p><a-pr>bar</a-pr><a-p>: </a-p><a-t>Option</a-t><a-p>&lt;</a-p><a-t>Bar</a-t><a-p>&gt;</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L348" href="#L348">348</a><span class="code-text"><a-p>}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L349" href="#L349">349</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L350" href="#L350">350</a><span class="code-text"><a-p>impl </a-p><a-t>Foo</a-t><a-p> {</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L351" href="#L351">351</a><span class="code-text"><a-p>    </a-p><a-k>fn</a-k><a-p> </a-p><a-f>new</a-f><a-p>() -&gt; </a-p><a-t>Foo</a-t><a-p> {</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L352" href="#L352">352</a><span class="code-text"><a-p>        </a-p><a-t>Foo</a-t><a-p> { </a-p><a-pr>bar</a-pr><a-p>: </a-p><a-cr>None</a-cr><a-p> }</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L353" href="#L353">353</a><span class="code-text"><a-p>    }</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L354" href="#L354">354</a><span class="code-text"><a-p>}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L355" href="#L355">355</a><span class="code-text"><a-p>```</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L356" href="#L356">356</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L357" href="#L357">357</a><span class="code-text"><a-p>Prefer `Default` even if it has to be implemented manually.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L358" href="#L358">358</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L359" href="#L359">359</a><span class="code-text"><a-p>**Rationale:** less typing in the common case, uniformity.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L360" href="#L360">360</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L361" href="#L361">361</a><span class="code-text"><a-p>Use `Vec::new` rather than `vec![]`.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L362" href="#L362">362</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L363" href="#L363">363</a><span class="code-text"><a-p>**Rationale:** uniformity, strength reduction.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L364" href="#L364">364</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L365" href="#L365">365</a><span class="code-text"><a-p>Avoid using &quot;dummy&quot; states to implement a `Default`.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L366" href="#L366">366</a><span class="code-text"><a-p>If a type doesn&#39;t have a sensible default, empty value, don&#39;t hide it.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L367" href="#L367">367</a><span class="code-text"><a-p>Let the caller explicitly decide what the right initial state is.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L368" href="#L368">368</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L369" href="#L369">369</a><span class="code-text"><a-p>## </a-p><a-tt>Functions Over Objects</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L370" href="#L370">370</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L371" href="#L371">371</a><span class="code-text"><a-p>Avoid creating &quot;doer&quot; objects.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L372" href="#L372">372</a><span class="code-text"><a-p>That is, objects which are created only to execute a single action.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L373" href="#L373">373</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L374" href="#L374">374</a><span class="code-text"><a-p>```</a-p><a-tl>rust</a-tl></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L375" href="#L375">375</a><span class="code-text"><a-p>// GOOD</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L376" href="#L376">376</a><span class="code-text"><a-p>do_thing(arg1, arg2);</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L377" href="#L377">377</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L378" href="#L378">378</a><span class="code-text"><a-p>// BAD</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L379" href="#L379">379</a><span class="code-text"><a-p>ThingDoer::</a-p><a-f>new</a-f><a-p>(arg1, arg2).</a-p><a-f>do</a-f><a-p>();</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L380" href="#L380">380</a><span class="code-text"><a-p>```</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L381" href="#L381">381</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L382" href="#L382">382</a><span class="code-text"><a-p>Note that this concerns only outward API.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L383" href="#L383">383</a><span class="code-text"><a-p>When implementing `do_thing`, it might be very useful to create a context object.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L384" href="#L384">384</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L385" href="#L385">385</a><span class="code-text"><a-p>```</a-p><a-tl>rust</a-tl></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L386" href="#L386">386</a><span class="code-text"><a-p>pub </a-p><a-k>fn</a-k><a-p> </a-p><a-f>do_thing</a-f><a-p>(</a-p><a-v>arg1</a-v><a-p>: </a-p><a-t>Arg1</a-t><a-p>, </a-p><a-v>arg2</a-v><a-p>: </a-p><a-t>Arg2</a-t><a-p>) -&gt; </a-p><a-t>Res</a-t><a-p> {</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L387" href="#L387">387</a><span class="code-text"><a-p>    </a-p><a-k>let</a-k><a-p> </a-p><a-k>mut</a-k><a-p> ctx = </a-p><a-t>Ctx</a-t><a-p> { arg1, arg2 };</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L388" href="#L388">388</a><span class="code-text"><a-p>    ctx.</a-p><a-f>run</a-f><a-p>()</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L389" href="#L389">389</a><span class="code-text"><a-p>}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L390" href="#L390">390</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L391" href="#L391">391</a><span class="code-text"><a-p>struct </a-p><a-t>Ctx</a-t><a-p> {</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L392" href="#L392">392</a><span class="code-text"><a-p>    </a-p><a-pr>arg1</a-pr><a-p>: </a-p><a-t>Arg1</a-t><a-p>, </a-p><a-pr>arg2</a-pr><a-p>: </a-p><a-t>Arg2</a-t></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L393" href="#L393">393</a><span class="code-text"><a-p>}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L394" href="#L394">394</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L395" href="#L395">395</a><span class="code-text"><a-p>impl </a-p><a-t>Ctx</a-t><a-p> {</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L396" href="#L396">396</a><span class="code-text"><a-p>    </a-p><a-k>fn</a-k><a-p> </a-p><a-f>run</a-f><a-p>(</a-p><a-v>self</a-v><a-p>) -&gt; </a-p><a-t>Res</a-t><a-p> {</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L397" href="#L397">397</a><span class="code-text"><a-p>        ...</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L398" href="#L398">398</a><span class="code-text"><a-p>    }</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L399" href="#L399">399</a><span class="code-text"><a-p>}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L400" href="#L400">400</a><span class="code-text"><a-p>```</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L401" href="#L401">401</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L402" href="#L402">402</a><span class="code-text"><a-p>The difference is that `Ctx` is an impl detail here.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L403" href="#L403">403</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L404" href="#L404">404</a><span class="code-text"><a-p>Sometimes a middle ground is acceptable if this can save some busywork:</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L405" href="#L405">405</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L406" href="#L406">406</a><span class="code-text"><a-p>```</a-p><a-tl>rust</a-tl></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L407" href="#L407">407</a><span class="code-text"><a-p>ThingDoer::</a-p><a-f>do</a-f><a-p>(arg1, arg2);</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L408" href="#L408">408</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L409" href="#L409">409</a><span class="code-text"><a-p>pub </a-p><a-k>struct</a-k><a-p> </a-p><a-t>ThingDoer</a-t><a-p> {</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L410" href="#L410">410</a><span class="code-text"><a-p>    </a-p><a-pr>arg1</a-pr><a-p>: </a-p><a-t>Arg1</a-t><a-p>, </a-p><a-pr>arg2</a-pr><a-p>: </a-p><a-t>Arg2</a-t><a-p>,</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L411" href="#L411">411</a><span class="code-text"><a-p>}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L412" href="#L412">412</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L413" href="#L413">413</a><span class="code-text"><a-p>impl </a-p><a-t>ThingDoer</a-t><a-p> {</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L414" href="#L414">414</a><span class="code-text"><a-p>    </a-p><a-k>pub</a-k><a-p> </a-p><a-k>fn</a-k><a-p> </a-p><a-f>do</a-f><a-p>(</a-p><a-v>arg1</a-v><a-p>: </a-p><a-t>Arg1</a-t><a-p>, </a-p><a-v>arg2</a-v><a-p>: </a-p><a-t>Arg2</a-t><a-p>) -&gt; </a-p><a-t>Res</a-t><a-p> {</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L415" href="#L415">415</a><span class="code-text"><a-p>        </a-p><a-t>ThingDoer</a-t><a-p> { arg1, arg2 }.</a-p><a-f>run</a-f><a-p>()</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L416" href="#L416">416</a><span class="code-text"><a-p>    }</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L417" href="#L417">417</a><span class="code-text"><a-p>    </a-p><a-k>fn</a-k><a-p> </a-p><a-f>run</a-f><a-p>(</a-p><a-v>self</a-v><a-p>) -&gt; </a-p><a-t>Res</a-t><a-p> {</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L418" href="#L418">418</a><span class="code-text"><a-p>        ...</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L419" href="#L419">419</a><span class="code-text"><a-p>    }</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L420" href="#L420">420</a><span class="code-text"><a-p>}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L421" href="#L421">421</a><span class="code-text"><a-p>```</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L422" href="#L422">422</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L423" href="#L423">423</a><span class="code-text"><a-p>**Rationale:** not bothering the caller with irrelevant details, not mixing user API with implementor API.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L424" href="#L424">424</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L425" href="#L425">425</a><span class="code-text"><a-p>## </a-p><a-tt>Functions with many parameters</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L426" href="#L426">426</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L427" href="#L427">427</a><span class="code-text"><a-p>Avoid creating functions with many optional or boolean parameters.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L428" href="#L428">428</a><span class="code-text"><a-p>Introduce a `Config` struct instead.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L429" href="#L429">429</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L430" href="#L430">430</a><span class="code-text"><a-p>```</a-p><a-tl>rust</a-tl></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L431" href="#L431">431</a><span class="code-text"><a-p>// GOOD</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L432" href="#L432">432</a><span class="code-text"><a-p>pub </a-p><a-k>struct</a-k><a-p> </a-p><a-t>AnnotationConfig</a-t><a-p> {</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L433" href="#L433">433</a><span class="code-text"><a-p>    </a-p><a-k>pub</a-k><a-p> </a-p><a-pr>binary_target</a-pr><a-p>: </a-p><a-t>bool</a-t><a-p>,</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L434" href="#L434">434</a><span class="code-text"><a-p>    </a-p><a-k>pub</a-k><a-p> </a-p><a-pr>annotate_runnables</a-pr><a-p>: </a-p><a-t>bool</a-t><a-p>,</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L435" href="#L435">435</a><span class="code-text"><a-p>    </a-p><a-k>pub</a-k><a-p> </a-p><a-pr>annotate_impls</a-pr><a-p>: </a-p><a-t>bool</a-t><a-p>,</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L436" href="#L436">436</a><span class="code-text"><a-p>}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L437" href="#L437">437</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L438" href="#L438">438</a><span class="code-text"><a-p>pub </a-p><a-k>fn</a-k><a-p> </a-p><a-f>annotations</a-f><a-p>(</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L439" href="#L439">439</a><span class="code-text"><a-p>    </a-p><a-v>db</a-v><a-p>: </a-p><a-o>&amp;</a-o><a-t>RootDatabase</a-t><a-p>,</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L440" href="#L440">440</a><span class="code-text"><a-p>    </a-p><a-v>file_id</a-v><a-p>: </a-p><a-t>FileId</a-t><a-p>,</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L441" href="#L441">441</a><span class="code-text"><a-p>    </a-p><a-v>config</a-v><a-p>: </a-p><a-t>AnnotationConfig</a-t></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L442" href="#L442">442</a><span class="code-text"><a-p>) -&gt; </a-p><a-t>Vec</a-t><a-p>&lt;</a-p><a-t>Annotation</a-t><a-p>&gt; {</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L443" href="#L443">443</a><span class="code-text"><a-p>    ...</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L444" href="#L444">444</a><span class="code-text"><a-p>}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L445" href="#L445">445</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L446" href="#L446">446</a><span class="code-text"><a-p>// BAD</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L447" href="#L447">447</a><span class="code-text"><a-p>pub </a-p><a-k>fn</a-k><a-p> </a-p><a-f>annotations</a-f><a-p>(</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L448" href="#L448">448</a><span class="code-text"><a-p>    </a-p><a-v>db</a-v><a-p>: </a-p><a-o>&amp;</a-o><a-t>RootDatabase</a-t><a-p>,</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L449" href="#L449">449</a><span class="code-text"><a-p>    </a-p><a-v>file_id</a-v><a-p>: </a-p><a-t>FileId</a-t><a-p>,</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L450" href="#L450">450</a><span class="code-text"><a-p>    </a-p><a-v>binary_target</a-v><a-p>: </a-p><a-t>bool</a-t><a-p>,</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L451" href="#L451">451</a><span class="code-text"><a-p>    </a-p><a-v>annotate_runnables</a-v><a-p>: </a-p><a-t>bool</a-t><a-p>,</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L452" href="#L452">452</a><span class="code-text"><a-p>    </a-p><a-v>annotate_impls</a-v><a-p>: </a-p><a-t>bool</a-t><a-p>,</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L453" href="#L453">453</a><span class="code-text"><a-p>) -&gt; </a-p><a-t>Vec</a-t><a-p>&lt;</a-p><a-t>Annotation</a-t><a-p>&gt; {</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L454" href="#L454">454</a><span class="code-text"><a-p>    ...</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L455" href="#L455">455</a><span class="code-text"><a-p>}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L456" href="#L456">456</a><span class="code-text"><a-p>```</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L457" href="#L457">457</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L458" href="#L458">458</a><span class="code-text"><a-pr>**Rationale:** reducing churn.</a-pr></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L459" href="#L459">459</a><span class="code-text"><a-pr>If the function has many parameters, they most likely change frequently.</a-pr></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L460" href="#L460">460</a><span class="code-text"><a-pr>By packing them into a struct we protect all intermediary functions from changes.</a-pr></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L461" href="#L461">461</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L462" href="#L462">462</a><span class="code-text"><a-pr>Do not implement `Default` for the `Config` struct, the caller has more context to determine better defaults.</a-pr></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L463" href="#L463">463</a><span class="code-text"><a-pr>Do not store `Config` as a part of the `state`, pass it explicitly.</a-pr></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L464" href="#L464">464</a><span class="code-text"><a-pr>This gives more flexibility for the caller.</a-pr></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L465" href="#L465">465</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L466" href="#L466">466</a><span class="code-text"><a-pr>If there is variation not only in the input parameters, but in the return type as well, consider introducing a `Command` type.</a-pr></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L467" href="#L467">467</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L468" href="#L468">468</a><span class="code-text"><a-p>```</a-p><a-tl>rust</a-tl></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L469" href="#L469">469</a><span class="code-text"><a-p>// MAYBE GOOD</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L470" href="#L470">470</a><span class="code-text"><a-p>pub </a-p><a-k>struct</a-k><a-p> </a-p><a-t>Query</a-t><a-p> {</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L471" href="#L471">471</a><span class="code-text"><a-p>    </a-p><a-k>pub</a-k><a-p> </a-p><a-pr>name</a-pr><a-p>: </a-p><a-t>String</a-t><a-p>,</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L472" href="#L472">472</a><span class="code-text"><a-p>    </a-p><a-k>pub</a-k><a-p> </a-p><a-pr>case_sensitive</a-pr><a-p>: </a-p><a-t>bool</a-t><a-p>,</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L473" href="#L473">473</a><span class="code-text"><a-p>}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L474" href="#L474">474</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L475" href="#L475">475</a><span class="code-text"><a-p>impl </a-p><a-t>Query</a-t><a-p> {</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L476" href="#L476">476</a><span class="code-text"><a-p>    </a-p><a-k>pub</a-k><a-p> </a-p><a-k>fn</a-k><a-p> </a-p><a-f>all</a-f><a-p>(</a-p><a-v>self</a-v><a-p>) -&gt; </a-p><a-t>Vec</a-t><a-p>&lt;</a-p><a-t>Item</a-t><a-p>&gt; { ...</a-p><a-pr> </a-pr><a-p>}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L477" href="#L477">477</a><span class="code-text"><a-p>    </a-p><a-k>pub</a-k><a-p> </a-p><a-k>fn</a-k><a-p> </a-p><a-f>first</a-f><a-p>(</a-p><a-v>self</a-v><a-p>) -&gt; </a-p><a-t>Option</a-t><a-p>&lt;</a-p><a-t>Item</a-t><a-p>&gt; { ...</a-p><a-pr> </a-pr><a-p>}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L478" href="#L478">478</a><span class="code-text"><a-p>}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L479" href="#L479">479</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L480" href="#L480">480</a><span class="code-text"><a-p>// MAYBE BAD</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L481" href="#L481">481</a><span class="code-text"><a-p>fn </a-p><a-f>query_all</a-f><a-p>(</a-p><a-v>name</a-v><a-p>: </a-p><a-t>String</a-t><a-p>, </a-p><a-v>case_sensitive</a-v><a-p>: </a-p><a-t>bool</a-t><a-p>) -&gt; </a-p><a-t>Vec</a-t><a-p>&lt;</a-p><a-t>Item</a-t><a-p>&gt; { ...</a-p><a-pr> </a-pr><a-p>}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L482" href="#L482">482</a><span class="code-text"><a-p>fn </a-p><a-f>query_first</a-f><a-p>(</a-p><a-v>name</a-v><a-p>: </a-p><a-t>String</a-t><a-p>, </a-p><a-v>case_sensitive</a-v><a-p>: </a-p><a-t>bool</a-t><a-p>) -&gt; </a-p><a-t>Option</a-t><a-p>&lt;</a-p><a-t>Item</a-t><a-p>&gt; { ...</a-p><a-pr> </a-pr><a-p>}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L483" href="#L483">483</a><span class="code-text"><a-p>```</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L484" href="#L484">484</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L485" href="#L485">485</a><span class="code-text"><a-p>##</a-p><a-pr> </a-pr><a-tt>Prefer Separate Functions Over Parameters</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L486" href="#L486">486</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L487" href="#L487">487</a><span class="code-text"><a-pr>If a function has a `bool` or an `Option` parameter, and it is always called with `true`, `false`, `Some` and `None` literals, split the function in two.</a-pr></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L488" href="#L488">488</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L489" href="#L489">489</a><span class="code-text"><a-p>```</a-p><a-tl>rust</a-tl></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L490" href="#L490">490</a><span class="code-text"><a-p>// GOOD</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L491" href="#L491">491</a><span class="code-text"><a-p>fn </a-p><a-f>caller_a</a-f><a-p>() {</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L492" href="#L492">492</a><span class="code-text"><a-p>    </a-p><a-f>foo</a-f><a-p>()</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L493" href="#L493">493</a><span class="code-text"><a-p>}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L494" href="#L494">494</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L495" href="#L495">495</a><span class="code-text"><a-p>fn </a-p><a-f>caller_b</a-f><a-p>() {</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L496" href="#L496">496</a><span class="code-text"><a-p>    </a-p><a-f>foo_with_bar</a-f><a-p>(</a-p><a-t>Bar</a-t><a-p>::</a-p><a-f>new</a-f><a-p>())</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L497" href="#L497">497</a><span class="code-text"><a-p>}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L498" href="#L498">498</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L499" href="#L499">499</a><span class="code-text"><a-p>fn </a-p><a-f>foo</a-f><a-p>() { ...</a-p><a-pr> </a-pr><a-p>}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L500" href="#L500">500</a><span class="code-text"><a-p>fn </a-p><a-f>foo_with_bar</a-f><a-p>(</a-p><a-v>bar</a-v><a-p>: </a-p><a-t>Bar</a-t><a-p>) { ...</a-p><a-pr> </a-pr><a-p>}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L501" href="#L501">501</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L502" href="#L502">502</a><span class="code-text"><a-p>// BAD</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L503" href="#L503">503</a><span class="code-text"><a-p>fn </a-p><a-f>caller_a</a-f><a-p>() {</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L504" href="#L504">504</a><span class="code-text"><a-p>    </a-p><a-f>foo</a-f><a-p>(</a-p><a-cr>None</a-cr><a-p>)</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L505" href="#L505">505</a><span class="code-text"><a-p>}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L506" href="#L506">506</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L507" href="#L507">507</a><span class="code-text"><a-p>fn </a-p><a-f>caller_b</a-f><a-p>() {</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L508" href="#L508">508</a><span class="code-text"><a-p>    </a-p><a-f>foo</a-f><a-p>(</a-p><a-f>Some</a-f><a-p>(</a-p><a-t>Bar</a-t><a-p>::</a-p><a-f>new</a-f><a-p>()))</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L509" href="#L509">509</a><span class="code-text"><a-p>}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L510" href="#L510">510</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L511" href="#L511">511</a><span class="code-text"><a-p>fn </a-p><a-f>foo</a-f><a-p>(</a-p><a-v>bar</a-v><a-p>: </a-p><a-t>Option</a-t><a-p>&lt;</a-p><a-t>Bar</a-t><a-p>&gt;) { ...</a-p><a-pr> </a-pr><a-p>}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L512" href="#L512">512</a><span class="code-text"><a-p>```</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L513" href="#L513">513</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L514" href="#L514">514</a><span class="code-text"><a-pr>**Rationale:** more often than not, such functions display &quot;`false sharing`&quot; -- they have additional `if` branching inside for two different cases.</a-pr></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L515" href="#L515">515</a><span class="code-text"><a-pr>Splitting the two different control flows into two functions simplifies each path, and remove cross-dependencies between the two paths.</a-pr></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L516" href="#L516">516</a><span class="code-text"><a-pr>If there&#39;s common code between `foo` and `foo_with_bar`, extract *that* into a common helper.</a-pr></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L517" href="#L517">517</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L518" href="#L518">518</a><span class="code-text"><a-p>##</a-p><a-pr> </a-pr><a-tt>Appropriate String Types</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L519" href="#L519">519</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L520" href="#L520">520</a><span class="code-text"><a-pr>When interfacing with OS APIs, use `OsString`, even if the original source of data is utf-8 encoded.</a-pr></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L521" href="#L521">521</a><span class="code-text"><a-pr>**Rationale:** cleanly delineates the boundary when the data goes into the OS-land.</a-pr></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L522" href="#L522">522</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L523" href="#L523">523</a><span class="code-text"><a-pr>Use `AbsPathBuf` and `AbsPath` over `std::Path`.</a-pr></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L524" href="#L524">524</a><span class="code-text"><a-pr>**Rationale:** rust-analyzer is a long-lived process which handles several projects at the same time.</a-pr></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L525" href="#L525">525</a><span class="code-text"><a-pr>It is important not to leak cwd by accident.</a-pr></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L526" href="#L526">526</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L527" href="#L527">527</a><span class="code-text"><a-p>#</a-p><a-pr> </a-pr><a-tt>Premature Pessimization</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L528" href="#L528">528</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L529" href="#L529">529</a><span class="code-text"><a-p>##</a-p><a-pr> </a-pr><a-tt>Avoid Allocations</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L530" href="#L530">530</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L531" href="#L531">531</a><span class="code-text"><a-pr>Avoid writing code which is slower than it needs to be.</a-pr></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L532" href="#L532">532</a><span class="code-text"><a-pr>Don&#39;t allocate a `Vec` where an iterator would do, don&#39;t allocate strings needlessly.</a-pr></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L533" href="#L533">533</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L534" href="#L534">534</a><span class="code-text"><a-p>```</a-p><a-tl>rust</a-tl></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L535" href="#L535">535</a><span class="code-text"><a-p>// GOOD</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L536" href="#L536">536</a><span class="code-text"><a-p>use itertools::</a-p><a-cr>Itertools</a-cr><a-p>;</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L537" href="#L537">537</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L538" href="#L538">538</a><span class="code-text"><a-p>let (first_word, second_word) = </a-p><a-k>match</a-k><a-p> text.</a-p><a-f>split_ascii_whitespace</a-f><a-p>().</a-p><a-f>collect_tuple</a-f><a-p>() {</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L539" href="#L539">539</a><span class="code-text"><a-p>    </a-p><a-cr>Some</a-cr><a-p>(it) =&gt; it,</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L540" href="#L540">540</a><span class="code-text"><a-p>    </a-p><a-cr>None</a-cr><a-p> =&gt; </a-p><a-k>return</a-k><a-p>,</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L541" href="#L541">541</a><span class="code-text"><a-p>}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L542" href="#L542">542</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L543" href="#L543">543</a><span class="code-text"><a-p>// BAD</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L544" href="#L544">544</a><span class="code-text"><a-p>let words = text.</a-p><a-f>split_ascii_whitespace</a-f><a-p>().</a-p><a-f>collect</a-f><a-p>::&lt;</a-p><a-t>Vec</a-t><a-p>&lt;</a-p><a-t>_</a-t><a-p>&gt;&gt;();</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L545" href="#L545">545</a><span class="code-text"><a-p>if words.</a-p><a-f>len</a-f><a-p>() != </a-p><a-co>2</a-co><a-p> {</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L546" href="#L546">546</a><span class="code-text"><a-p>    </a-p><a-k>return</a-k></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L547" href="#L547">547</a><span class="code-text"><a-p>}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L548" href="#L548">548</a><span class="code-text"><a-p>```</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L549" href="#L549">549</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L550" href="#L550">550</a><span class="code-text"><a-p>**Rationale:** not allocating is almost always faster.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L551" href="#L551">551</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L552" href="#L552">552</a><span class="code-text"><a-p>## </a-p><a-tt>Push Allocations to the Call Site</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L553" href="#L553">553</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L554" href="#L554">554</a><span class="code-text"><a-p>If allocation is inevitable, let the caller allocate the resource:</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L555" href="#L555">555</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L556" href="#L556">556</a><span class="code-text"><a-p>```</a-p><a-tl>rust</a-tl></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L557" href="#L557">557</a><span class="code-text"><a-p>// GOOD</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L558" href="#L558">558</a><span class="code-text"><a-p>fn </a-p><a-f>frobnicate</a-f><a-p>(</a-p><a-v>s</a-v><a-p>: </a-p><a-t>String</a-t><a-p>) {</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L559" href="#L559">559</a><span class="code-text"><a-p>    ...</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L560" href="#L560">560</a><span class="code-text"><a-p>}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L561" href="#L561">561</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L562" href="#L562">562</a><span class="code-text"><a-p>// BAD</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L563" href="#L563">563</a><span class="code-text"><a-p>fn </a-p><a-f>frobnicate</a-f><a-p>(</a-p><a-v>s</a-v><a-p>: </a-p><a-o>&amp;</a-o><a-t>str</a-t><a-p>) {</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L564" href="#L564">564</a><span class="code-text"><a-p>    </a-p><a-k>let</a-k><a-p> s = s.</a-p><a-f>to_string</a-f><a-p>();</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L565" href="#L565">565</a><span class="code-text"><a-p>    ...</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L566" href="#L566">566</a><span class="code-text"><a-p>}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L567" href="#L567">567</a><span class="code-text"><a-p>```</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L568" href="#L568">568</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L569" href="#L569">569</a><span class="code-text"><a-pr>**Rationale:** reveals the costs.</a-pr></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L570" href="#L570">570</a><span class="code-text"><a-pr>It is also more efficient when the caller already owns the allocation.</a-pr></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L571" href="#L571">571</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L572" href="#L572">572</a><span class="code-text"><a-p>##</a-p><a-pr> </a-pr><a-tt>Collection Types</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L573" href="#L573">573</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L574" href="#L574">574</a><span class="code-text"><a-pr>Prefer `rustc_hash::FxHashMap` and `rustc_hash::FxHashSet` instead of the ones in `std::collections`.</a-pr></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L575" href="#L575">575</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L576" href="#L576">576</a><span class="code-text"><a-pr>**Rationale:** they use a hasher that&#39;s significantly faster and using them consistently will reduce code size by some small amount.</a-pr></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L577" href="#L577">577</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L578" href="#L578">578</a><span class="code-text"><a-p>##</a-p><a-pr> </a-pr><a-tt>Avoid Intermediate Collections</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L579" href="#L579">579</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L580" href="#L580">580</a><span class="code-text"><a-pr>When writing a recursive function to compute a sets of things, use an accumulator parameter instead of returning a fresh collection.</a-pr></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L581" href="#L581">581</a><span class="code-text"><a-pr>Accumulator goes first in the list of arguments.</a-pr></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L582" href="#L582">582</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L583" href="#L583">583</a><span class="code-text"><a-p>```</a-p><a-tl>rust</a-tl></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L584" href="#L584">584</a><span class="code-text"><a-p>// GOOD</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L585" href="#L585">585</a><span class="code-text"><a-p>pub </a-p><a-k>fn</a-k><a-p> </a-p><a-f>reachable_nodes</a-f><a-p>(</a-p><a-v>node</a-v><a-p>: </a-p><a-t>Node</a-t><a-p>) -&gt; </a-p><a-t>FxHashSet</a-t><a-p>&lt;</a-p><a-t>Node</a-t><a-p>&gt; {</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L586" href="#L586">586</a><span class="code-text"><a-p>    </a-p><a-k>let</a-k><a-p> </a-p><a-k>mut</a-k><a-p> res = </a-p><a-t>FxHashSet</a-t><a-p>::</a-p><a-f>default</a-f><a-p>();</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L587" href="#L587">587</a><span class="code-text"><a-p>    </a-p><a-f>go</a-f><a-p>(</a-p><a-o>&amp;</a-o><a-k>mut</a-k><a-p> res, node);</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L588" href="#L588">588</a><span class="code-text"><a-p>    res</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L589" href="#L589">589</a><span class="code-text"><a-p>}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L590" href="#L590">590</a><span class="code-text"><a-p>fn </a-p><a-f>go</a-f><a-p>(</a-p><a-v>acc</a-v><a-p>: </a-p><a-o>&amp;</a-o><a-k>mut</a-k><a-p> </a-p><a-t>FxHashSet</a-t><a-p>&lt;</a-p><a-t>Node</a-t><a-p>&gt;, </a-p><a-v>node</a-v><a-p>: </a-p><a-t>Node</a-t><a-p>) {</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L591" href="#L591">591</a><span class="code-text"><a-p>    acc.</a-p><a-f>insert</a-f><a-p>(node);</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L592" href="#L592">592</a><span class="code-text"><a-p>    </a-p><a-k>for</a-k><a-p> n </a-p><a-k>in</a-k><a-p> node.</a-p><a-f>neighbors</a-f><a-p>() {</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L593" href="#L593">593</a><span class="code-text"><a-p>        </a-p><a-f>go</a-f><a-p>(acc, n);</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L594" href="#L594">594</a><span class="code-text"><a-p>    }</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L595" href="#L595">595</a><span class="code-text"><a-p>}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L596" href="#L596">596</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L597" href="#L597">597</a><span class="code-text"><a-p>// BAD</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L598" href="#L598">598</a><span class="code-text"><a-p>pub </a-p><a-k>fn</a-k><a-p> </a-p><a-f>reachable_nodes</a-f><a-p>(</a-p><a-v>node</a-v><a-p>: </a-p><a-t>Node</a-t><a-p>) -&gt; </a-p><a-t>FxHashSet</a-t><a-p>&lt;</a-p><a-t>Node</a-t><a-p>&gt; {</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L599" href="#L599">599</a><span class="code-text"><a-p>    </a-p><a-k>let</a-k><a-p> </a-p><a-k>mut</a-k><a-p> res = </a-p><a-t>FxHashSet</a-t><a-p>::</a-p><a-f>default</a-f><a-p>();</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L600" href="#L600">600</a><span class="code-text"><a-p>    res.</a-p><a-f>insert</a-f><a-p>(node);</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L601" href="#L601">601</a><span class="code-text"><a-p>    </a-p><a-k>for</a-k><a-p> n </a-p><a-k>in</a-k><a-p> node.</a-p><a-f>neighbors</a-f><a-p>() {</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L602" href="#L602">602</a><span class="code-text"><a-p>        res.</a-p><a-f>extend</a-f><a-p>(</a-p><a-f>reachable_nodes</a-f><a-p>(n));</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L603" href="#L603">603</a><span class="code-text"><a-p>    }</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L604" href="#L604">604</a><span class="code-text"><a-p>    res</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L605" href="#L605">605</a><span class="code-text"><a-p>}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L606" href="#L606">606</a><span class="code-text"><a-p>```</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L607" href="#L607">607</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L608" href="#L608">608</a><span class="code-text"><a-p>**Rationale:** re-use allocations, accumulator style is more concise for complex cases.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L609" href="#L609">609</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L610" href="#L610">610</a><span class="code-text"><a-p>## </a-p><a-tt>Avoid Monomorphization</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L611" href="#L611">611</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L612" href="#L612">612</a><span class="code-text"><a-p>Avoid making a lot of code type parametric, *especially* on the boundaries between crates.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L613" href="#L613">613</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L614" href="#L614">614</a><span class="code-text"><a-p>```</a-p><a-tl>rust</a-tl></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L615" href="#L615">615</a><span class="code-text"><a-p>// GOOD</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L616" href="#L616">616</a><span class="code-text"><a-p>fn </a-p><a-f>frobnicate</a-f><a-p>(</a-p><a-v>f</a-v><a-p>: </a-p><a-k>impl</a-k><a-p> </a-p><a-t>FnMut</a-t><a-p>()) {</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L617" href="#L617">617</a><span class="code-text"><a-p>    </a-p><a-f>frobnicate_impl</a-f><a-p>(</a-p><a-o>&amp;</a-o><a-k>mut</a-k><a-p> f)</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L618" href="#L618">618</a><span class="code-text"><a-p>}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L619" href="#L619">619</a><span class="code-text"><a-p>fn </a-p><a-f>frobnicate_impl</a-f><a-p>(</a-p><a-v>f</a-v><a-p>: </a-p><a-o>&amp;</a-o><a-k>mut</a-k><a-p> </a-p><a-k>dyn</a-k><a-p> </a-p><a-t>FnMut</a-t><a-p>()) {</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L620" href="#L620">620</a><span class="code-text"><a-p>    </a-p><a-c>// lots of code</a-c></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L621" href="#L621">621</a><span class="code-text"><a-p>}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L622" href="#L622">622</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L623" href="#L623">623</a><span class="code-text"><a-p>// BAD</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L624" href="#L624">624</a><span class="code-text"><a-p>fn </a-p><a-f>frobnicate</a-f><a-p>(</a-p><a-v>f</a-v><a-p>: </a-p><a-k>impl</a-k><a-p> </a-p><a-t>FnMut</a-t><a-p>()) {</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L625" href="#L625">625</a><span class="code-text"><a-p>    </a-p><a-c>// lots of code</a-c></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L626" href="#L626">626</a><span class="code-text"><a-p>}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L627" href="#L627">627</a><span class="code-text"><a-p>```</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L628" href="#L628">628</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L629" href="#L629">629</a><span class="code-text"><a-p>Avoid `AsRef` polymorphism, it pays back only for widely used libraries:</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L630" href="#L630">630</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L631" href="#L631">631</a><span class="code-text"><a-p>```</a-p><a-tl>rust</a-tl></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L632" href="#L632">632</a><span class="code-text"><a-p>// GOOD</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L633" href="#L633">633</a><span class="code-text"><a-p>fn </a-p><a-f>frobnicate</a-f><a-p>(</a-p><a-v>f</a-v><a-p>: </a-p><a-o>&amp;</a-o><a-t>Path</a-t><a-p>) {</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L634" href="#L634">634</a><span class="code-text"><a-p>}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L635" href="#L635">635</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L636" href="#L636">636</a><span class="code-text"><a-p>// BAD</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L637" href="#L637">637</a><span class="code-text"><a-p>fn </a-p><a-f>frobnicate</a-f><a-p>(</a-p><a-v>f</a-v><a-p>: </a-p><a-k>impl</a-k><a-p> </a-p><a-t>AsRef</a-t><a-p>&lt;</a-p><a-t>Path</a-t><a-p>&gt;) {</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L638" href="#L638">638</a><span class="code-text"><a-p>}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L639" href="#L639">639</a><span class="code-text"><a-p>```</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L640" href="#L640">640</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L641" href="#L641">641</a><span class="code-text"><a-p>**Rationale:** Rust uses monomorphization to compile generic code, meaning that for each instantiation of a generic functions with concrete types, the function is compiled afresh, *per crate*.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L642" href="#L642">642</a><span class="code-text"><a-p>This allows for exceptionally good performance, but leads to increased compile times.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L643" href="#L643">643</a><span class="code-text"><a-p>Runtime performance obeys 80%/20% rule -- only a small fraction of code is hot.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L644" href="#L644">644</a><span class="code-text"><a-p>Compile time **does not** obey this rule -- all code has to be compiled.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L645" href="#L645">645</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L646" href="#L646">646</a><span class="code-text"><a-p># </a-p><a-tt>Style</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L647" href="#L647">647</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L648" href="#L648">648</a><span class="code-text"><a-p>## </a-p><a-tt>Order of Imports</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L649" href="#L649">649</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L650" href="#L650">650</a><span class="code-text"><a-p>Separate import groups with blank lines.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L651" href="#L651">651</a><span class="code-text"><a-p>Use one `use` per crate.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L652" href="#L652">652</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L653" href="#L653">653</a><span class="code-text"><a-p>Module declarations come before the imports.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L654" href="#L654">654</a><span class="code-text"><a-p>Order them in &quot;suggested reading order&quot; for a person new to the code base.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L655" href="#L655">655</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L656" href="#L656">656</a><span class="code-text"><a-p>```</a-p><a-tl>rust</a-tl></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L657" href="#L657">657</a><span class="code-text"><a-p>mod x;</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L658" href="#L658">658</a><span class="code-text"><a-p>mod y;</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L659" href="#L659">659</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L660" href="#L660">660</a><span class="code-text"><a-p>// First std.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L661" href="#L661">661</a><span class="code-text"><a-p>use std::{ ... }</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L662" href="#L662">662</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L663" href="#L663">663</a><span class="code-text"><a-p>// Second, external crates (both crates.io crates and other rust-analyzer crates).</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L664" href="#L664">664</a><span class="code-text"><a-p>use crate_foo::{ ... }</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L665" href="#L665">665</a><span class="code-text"><a-p>use crate_bar::{ ... }</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L666" href="#L666">666</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L667" href="#L667">667</a><span class="code-text"><a-p>// Then current crate.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L668" href="#L668">668</a><span class="code-text"><a-p>use </a-p><a-k>crate</a-k><a-p>::{}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L669" href="#L669">669</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L670" href="#L670">670</a><span class="code-text"><a-p>// Finally, parent and child modules, but prefer `use crate::`.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L671" href="#L671">671</a><span class="code-text"><a-p>use </a-p><a-k>super</a-k><a-p>::{}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L672" href="#L672">672</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L673" href="#L673">673</a><span class="code-text"><a-p>// Re-exports are treated as item definitions rather than imports, so they go</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L674" href="#L674">674</a><span class="code-text"><a-p>// after imports and modules. Use them sparingly.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L675" href="#L675">675</a><span class="code-text"><a-p>pub </a-p><a-k>use</a-k><a-p> </a-p><a-k>crate</a-k><a-p>::x::</a-p><a-cr>Z</a-cr><a-p>;</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L676" href="#L676">676</a><span class="code-text"><a-p>```</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L677" href="#L677">677</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L678" href="#L678">678</a><span class="code-text"><a-p>**Rationale:** consistency.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L679" href="#L679">679</a><span class="code-text"><a-p>Reading order is important for new contributors.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L680" href="#L680">680</a><span class="code-text"><a-p>Grouping by crate allows spotting unwanted dependencies easier.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L681" href="#L681">681</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L682" href="#L682">682</a><span class="code-text"><a-p>## </a-p><a-tt>Import Style</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L683" href="#L683">683</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L684" href="#L684">684</a><span class="code-text"><a-p>Qualify items from `hir` and `ast`.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L685" href="#L685">685</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L686" href="#L686">686</a><span class="code-text"><a-p>```</a-p><a-tl>rust</a-tl></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L687" href="#L687">687</a><span class="code-text"><a-p>// GOOD</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L688" href="#L688">688</a><span class="code-text"><a-p>use syntax::ast;</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L689" href="#L689">689</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L690" href="#L690">690</a><span class="code-text"><a-p>fn </a-p><a-f>frobnicate</a-f><a-p>(</a-p><a-v>func</a-v><a-p>: hir::</a-p><a-t>Function</a-t><a-p>, </a-p><a-v>strukt</a-v><a-p>: ast::</a-p><a-t>Struct</a-t><a-p>) {}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L691" href="#L691">691</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L692" href="#L692">692</a><span class="code-text"><a-p>// BAD</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L693" href="#L693">693</a><span class="code-text"><a-p>use hir::</a-p><a-cr>Function</a-cr><a-p>;</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L694" href="#L694">694</a><span class="code-text"><a-p>use syntax::ast::</a-p><a-cr>Struct</a-cr><a-p>;</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L695" href="#L695">695</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L696" href="#L696">696</a><span class="code-text"><a-p>fn </a-p><a-f>frobnicate</a-f><a-p>(</a-p><a-v>func</a-v><a-p>: </a-p><a-t>Function</a-t><a-p>, </a-p><a-v>strukt</a-v><a-p>: </a-p><a-t>Struct</a-t><a-p>) {}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L697" href="#L697">697</a><span class="code-text"><a-p>```</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L698" href="#L698">698</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L699" href="#L699">699</a><span class="code-text"><a-p>**Rationale:** avoids name clashes, makes the layer clear at a glance.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L700" href="#L700">700</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L701" href="#L701">701</a><span class="code-text"><a-p>When implementing traits from `std::fmt` or `std::ops`, import the module:</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L702" href="#L702">702</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L703" href="#L703">703</a><span class="code-text"><a-p>```</a-p><a-tl>rust</a-tl></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L704" href="#L704">704</a><span class="code-text"><a-p>// GOOD</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L705" href="#L705">705</a><span class="code-text"><a-p>use std::fmt;</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L706" href="#L706">706</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L707" href="#L707">707</a><span class="code-text"><a-p>impl fmt::</a-p><a-t>Display</a-t><a-p> </a-p><a-k>for</a-k><a-p> </a-p><a-t>RenameError</a-t><a-p> {</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L708" href="#L708">708</a><span class="code-text"><a-p>    </a-p><a-k>fn</a-k><a-p> </a-p><a-f>fmt</a-f><a-p>(</a-p><a-o>&amp;</a-o><a-v>self</a-v><a-p>, </a-p><a-v>f</a-v><a-p>: </a-p><a-o>&amp;</a-o><a-k>mut</a-k><a-p> fmt::</a-p><a-t>Formatter</a-t><a-p>&lt;</a-p><a-o>&#39;</a-o><a-l>_</a-l><a-p>&gt;) -&gt; fmt::</a-p><a-t>Result</a-t><a-p> { .. }</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L709" href="#L709">709</a><span class="code-text"><a-p>}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L710" href="#L710">710</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L711" href="#L711">711</a><span class="code-text"><a-p>// BAD</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L712" href="#L712">712</a><span class="code-text"><a-p>impl std::fmt::</a-p><a-t>Display</a-t><a-p> </a-p><a-k>for</a-k><a-p> </a-p><a-t>RenameError</a-t><a-p> {</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L713" href="#L713">713</a><span class="code-text"><a-p>    </a-p><a-k>fn</a-k><a-p> </a-p><a-f>fmt</a-f><a-p>(</a-p><a-o>&amp;</a-o><a-v>self</a-v><a-p>, </a-p><a-v>f</a-v><a-p>: </a-p><a-o>&amp;</a-o><a-k>mut</a-k><a-p> std::fmt::</a-p><a-t>Formatter</a-t><a-p>&lt;</a-p><a-o>&#39;</a-o><a-l>_</a-l><a-p>&gt;) -&gt; std::fmt::</a-p><a-t>Result</a-t><a-p> { .. }</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L714" href="#L714">714</a><span class="code-text"><a-p>}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L715" href="#L715">715</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L716" href="#L716">716</a><span class="code-text"><a-p>// BAD</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L717" href="#L717">717</a><span class="code-text"><a-p>use std::ops::</a-p><a-cr>Deref</a-cr><a-p>;</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L718" href="#L718">718</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L719" href="#L719">719</a><span class="code-text"><a-p>impl </a-p><a-t>Deref</a-t><a-p> </a-p><a-k>for</a-k><a-p> </a-p><a-t>Widget</a-t><a-p> {</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L720" href="#L720">720</a><span class="code-text"><a-p>    </a-p><a-k>type</a-k><a-p> </a-p><a-t>Target</a-t><a-p> = </a-p><a-t>str</a-t><a-p>;</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L721" href="#L721">721</a><span class="code-text"><a-p>    </a-p><a-k>fn</a-k><a-p> </a-p><a-f>deref</a-f><a-p>(</a-p><a-o>&amp;</a-o><a-v>self</a-v><a-p>) -&gt; </a-p><a-o>&amp;</a-o><a-t>str</a-t><a-p> { .. }</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L722" href="#L722">722</a><span class="code-text"><a-p>}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L723" href="#L723">723</a><span class="code-text"><a-p>```</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L724" href="#L724">724</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L725" href="#L725">725</a><span class="code-text"><a-p>**Rationale:** overall, less typing.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L726" href="#L726">726</a><span class="code-text"><a-p>Makes it clear that a trait is implemented, rather than used.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L727" href="#L727">727</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L728" href="#L728">728</a><span class="code-text"><a-p>Avoid local `use MyEnum::*` imports.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L729" href="#L729">729</a><span class="code-text"><a-p>**Rationale:** consistency.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L730" href="#L730">730</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L731" href="#L731">731</a><span class="code-text"><a-p>Prefer `use crate::foo::bar` to `use super::bar` or `use self::bar::baz`.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L732" href="#L732">732</a><span class="code-text"><a-p>**Rationale:** consistency, this is the style which works in all cases.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L733" href="#L733">733</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L734" href="#L734">734</a><span class="code-text"><a-p>By default, avoid re-exports.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L735" href="#L735">735</a><span class="code-text"><a-p>**Rationale:** for non-library code, re-exports introduce two ways to use something and allow for inconsistency.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L736" href="#L736">736</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L737" href="#L737">737</a><span class="code-text"><a-p>## </a-p><a-tt>Order of Items</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L738" href="#L738">738</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L739" href="#L739">739</a><span class="code-text"><a-p>Optimize for the reader who sees the file for the first time, and wants to get a general idea about what&#39;s going on.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L740" href="#L740">740</a><span class="code-text"><a-p>People read things from top to bottom, so place most important things first.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L741" href="#L741">741</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L742" href="#L742">742</a><span class="code-text"><a-p>Specifically, if all items except one are private, always put the non-private item on top.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L743" href="#L743">743</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L744" href="#L744">744</a><span class="code-text"><a-p>```</a-p><a-tl>rust</a-tl></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L745" href="#L745">745</a><span class="code-text"><a-p>// GOOD</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L746" href="#L746">746</a><span class="code-text"><a-p>pub(</a-p><a-k>crate</a-k><a-p>) </a-p><a-k>fn</a-k><a-p> </a-p><a-f>frobnicate</a-f><a-p>() {</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L747" href="#L747">747</a><span class="code-text"><a-p>    </a-p><a-t>Helper</a-t><a-p>::</a-p><a-f>act</a-f><a-p>()</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L748" href="#L748">748</a><span class="code-text"><a-p>}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L749" href="#L749">749</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L750" href="#L750">750</a><span class="code-text"><a-p>#[derive(</a-p><a-cr>Default</a-cr><a-p>)]</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L751" href="#L751">751</a><span class="code-text"><a-p>struct </a-p><a-t>Helper</a-t><a-p> { </a-p><a-pr>stuff</a-pr><a-p>: </a-p><a-t>i32</a-t><a-p> }</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L752" href="#L752">752</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L753" href="#L753">753</a><span class="code-text"><a-p>impl </a-p><a-t>Helper</a-t><a-p> {</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L754" href="#L754">754</a><span class="code-text"><a-p>    </a-p><a-k>fn</a-k><a-p> </a-p><a-f>act</a-f><a-p>(</a-p><a-o>&amp;</a-o><a-v>self</a-v><a-p>) {</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L755" href="#L755">755</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L756" href="#L756">756</a><span class="code-text"><a-p>    }</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L757" href="#L757">757</a><span class="code-text"><a-p>}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L758" href="#L758">758</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L759" href="#L759">759</a><span class="code-text"><a-p>// BAD</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L760" href="#L760">760</a><span class="code-text"><a-p>#[derive(</a-p><a-cr>Default</a-cr><a-p>)]</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L761" href="#L761">761</a><span class="code-text"><a-p>struct </a-p><a-t>Helper</a-t><a-p> { </a-p><a-pr>stuff</a-pr><a-p>: </a-p><a-t>i32</a-t><a-p> }</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L762" href="#L762">762</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L763" href="#L763">763</a><span class="code-text"><a-p>pub(</a-p><a-k>crate</a-k><a-p>) </a-p><a-k>fn</a-k><a-p> </a-p><a-f>frobnicate</a-f><a-p>() {</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L764" href="#L764">764</a><span class="code-text"><a-p>    </a-p><a-t>Helper</a-t><a-p>::</a-p><a-f>act</a-f><a-p>()</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L765" href="#L765">765</a><span class="code-text"><a-p>}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L766" href="#L766">766</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L767" href="#L767">767</a><span class="code-text"><a-p>impl </a-p><a-t>Helper</a-t><a-p> {</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L768" href="#L768">768</a><span class="code-text"><a-p>    </a-p><a-k>fn</a-k><a-p> </a-p><a-f>act</a-f><a-p>(</a-p><a-o>&amp;</a-o><a-v>self</a-v><a-p>) {</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L769" href="#L769">769</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L770" href="#L770">770</a><span class="code-text"><a-p>    }</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L771" href="#L771">771</a><span class="code-text"><a-p>}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L772" href="#L772">772</a><span class="code-text"><a-p>```</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L773" href="#L773">773</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L774" href="#L774">774</a><span class="code-text"><a-p>If there&#39;s a mixture of private and public items, put public items first.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L775" href="#L775">775</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L776" href="#L776">776</a><span class="code-text"><a-p>Put `struct`s and `enum`s first, functions and impls last. Order type declarations in top-down manner.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L777" href="#L777">777</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L778" href="#L778">778</a><span class="code-text"><a-p>```</a-p><a-tl>rust</a-tl></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L779" href="#L779">779</a><span class="code-text"><a-p>// GOOD</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L780" href="#L780">780</a><span class="code-text"><a-p>struct </a-p><a-t>Parent</a-t><a-p> {</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L781" href="#L781">781</a><span class="code-text"><a-p>    </a-p><a-pr>children</a-pr><a-p>: </a-p><a-t>Vec</a-t><a-p>&lt;</a-p><a-t>Child</a-t><a-p>&gt;</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L782" href="#L782">782</a><span class="code-text"><a-p>}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L783" href="#L783">783</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L784" href="#L784">784</a><span class="code-text"><a-p>struct </a-p><a-t>Child</a-t><a-p>;</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L785" href="#L785">785</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L786" href="#L786">786</a><span class="code-text"><a-p>impl </a-p><a-t>Parent</a-t><a-p> {</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L787" href="#L787">787</a><span class="code-text"><a-p>}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L788" href="#L788">788</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L789" href="#L789">789</a><span class="code-text"><a-p>impl </a-p><a-t>Child</a-t><a-p> {</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L790" href="#L790">790</a><span class="code-text"><a-p>}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L791" href="#L791">791</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L792" href="#L792">792</a><span class="code-text"><a-p>// BAD</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L793" href="#L793">793</a><span class="code-text"><a-p>struct </a-p><a-t>Child</a-t><a-p>;</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L794" href="#L794">794</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L795" href="#L795">795</a><span class="code-text"><a-p>impl </a-p><a-t>Child</a-t><a-p> {</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L796" href="#L796">796</a><span class="code-text"><a-p>}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L797" href="#L797">797</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L798" href="#L798">798</a><span class="code-text"><a-p>struct </a-p><a-t>Parent</a-t><a-p> {</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L799" href="#L799">799</a><span class="code-text"><a-p>    </a-p><a-pr>children</a-pr><a-p>: </a-p><a-t>Vec</a-t><a-p>&lt;</a-p><a-t>Child</a-t><a-p>&gt;</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L800" href="#L800">800</a><span class="code-text"><a-p>}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L801" href="#L801">801</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L802" href="#L802">802</a><span class="code-text"><a-p>impl </a-p><a-t>Parent</a-t><a-p> {</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L803" href="#L803">803</a><span class="code-text"><a-p>}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L804" href="#L804">804</a><span class="code-text"><a-p>```</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L805" href="#L805">805</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L806" href="#L806">806</a><span class="code-text"><a-p>**Rationale:** easier to get the sense of the API by visually scanning the file.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L807" href="#L807">807</a><span class="code-text"><a-p>If function bodies are folded in the editor, the source code should read as documentation for the public API.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L808" href="#L808">808</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L809" href="#L809">809</a><span class="code-text"><a-p>## </a-p><a-tt>Context Parameters</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L810" href="#L810">810</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L811" href="#L811">811</a><span class="code-text"><a-p>Some parameters are threaded unchanged through many function calls.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L812" href="#L812">812</a><span class="code-text"><a-p>They determine the &quot;context&quot; of the operation.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L813" href="#L813">813</a><span class="code-text"><a-p>Pass such parameters first, not last.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L814" href="#L814">814</a><span class="code-text"><a-p>If there are several context parameters, consider packing them into a `struct Ctx` and passing it as `&amp;self`.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L815" href="#L815">815</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L816" href="#L816">816</a><span class="code-text"><a-p>```</a-p><a-tl>rust</a-tl></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L817" href="#L817">817</a><span class="code-text"><a-p>// GOOD</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L818" href="#L818">818</a><span class="code-text"><a-p>fn </a-p><a-f>dfs</a-f><a-p>(</a-p><a-v>graph</a-v><a-p>: </a-p><a-o>&amp;</a-o><a-t>Graph</a-t><a-p>, </a-p><a-v>v</a-v><a-p>: </a-p><a-t>Vertex</a-t><a-p>) -&gt; </a-p><a-t>usize</a-t><a-p> {</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L819" href="#L819">819</a><span class="code-text"><a-p>    </a-p><a-k>let</a-k><a-p> </a-p><a-k>mut</a-k><a-p> visited = </a-p><a-t>FxHashSet</a-t><a-p>::</a-p><a-f>default</a-f><a-p>();</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L820" href="#L820">820</a><span class="code-text"><a-p>    </a-p><a-k>return</a-k><a-p> </a-p><a-f>go</a-f><a-p>(graph, </a-p><a-o>&amp;</a-o><a-k>mut</a-k><a-p> visited, v);</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L821" href="#L821">821</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L822" href="#L822">822</a><span class="code-text"><a-p>    </a-p><a-k>fn</a-k><a-p> </a-p><a-f>go</a-f><a-p>(</a-p><a-v>graph</a-v><a-p>: </a-p><a-o>&amp;</a-o><a-t>Graph</a-t><a-p>, </a-p><a-v>visited</a-v><a-p>: </a-p><a-o>&amp;</a-o><a-k>mut</a-k><a-p> </a-p><a-t>FxHashSet</a-t><a-p>&lt;</a-p><a-t>Vertex</a-t><a-p>&gt;, </a-p><a-v>v</a-v><a-p>: </a-p><a-t>usize</a-t><a-p>) -&gt; </a-p><a-t>usize</a-t><a-p> {</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L823" href="#L823">823</a><span class="code-text"><a-p>        ...</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L824" href="#L824">824</a><span class="code-text"><a-p>    }</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L825" href="#L825">825</a><span class="code-text"><a-p>}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L826" href="#L826">826</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L827" href="#L827">827</a><span class="code-text"><a-p>// BAD</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L828" href="#L828">828</a><span class="code-text"><a-p>fn </a-p><a-f>dfs</a-f><a-p>(</a-p><a-v>v</a-v><a-p>: </a-p><a-t>Vertex</a-t><a-p>, </a-p><a-v>graph</a-v><a-p>: </a-p><a-o>&amp;</a-o><a-t>Graph</a-t><a-p>) -&gt; </a-p><a-t>usize</a-t><a-p> {</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L829" href="#L829">829</a><span class="code-text"><a-p>    </a-p><a-k>fn</a-k><a-p> </a-p><a-f>go</a-f><a-p>(</a-p><a-v>v</a-v><a-p>: </a-p><a-t>usize</a-t><a-p>, </a-p><a-v>graph</a-v><a-p>: </a-p><a-o>&amp;</a-o><a-t>Graph</a-t><a-p>, </a-p><a-v>visited</a-v><a-p>: </a-p><a-o>&amp;</a-o><a-k>mut</a-k><a-p> </a-p><a-t>FxHashSet</a-t><a-p>&lt;</a-p><a-t>Vertex</a-t><a-p>&gt;) -&gt; </a-p><a-t>usize</a-t><a-p> {</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L830" href="#L830">830</a><span class="code-text"><a-p>        ...</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L831" href="#L831">831</a><span class="code-text"><a-p>    }</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L832" href="#L832">832</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L833" href="#L833">833</a><span class="code-text"><a-p>    </a-p><a-k>let</a-k><a-p> </a-p><a-k>mut</a-k><a-p> visited = </a-p><a-t>FxHashSet</a-t><a-p>::</a-p><a-f>default</a-f><a-p>();</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L834" href="#L834">834</a><span class="code-text"><a-p>    </a-p><a-f>go</a-f><a-p>(v, graph, </a-p><a-o>&amp;</a-o><a-k>mut</a-k><a-p> visited)</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L835" href="#L835">835</a><span class="code-text"><a-p>}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L836" href="#L836">836</a><span class="code-text"><a-p>```</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L837" href="#L837">837</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L838" href="#L838">838</a><span class="code-text"><a-p>**Rationale:** consistency.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L839" href="#L839">839</a><span class="code-text"><a-p>Context-first works better when non-context parameter is a lambda.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L840" href="#L840">840</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L841" href="#L841">841</a><span class="code-text"><a-p>## </a-p><a-tt>Variable Naming</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L842" href="#L842">842</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L843" href="#L843">843</a><span class="code-text"><a-p>Use boring and long names for local variables ([yay code completion](https://github.com/rust-lang/rust-analyzer/pull/4162#discussion_r417130973)).</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L844" href="#L844">844</a><span class="code-text"><a-p>The default name is a lowercased name of the type: `global_state: GlobalState`.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L845" href="#L845">845</a><span class="code-text"><a-p>Avoid ad-hoc acronyms and contractions, but use the ones that exist consistently (`db`, `ctx`, `acc`).</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L846" href="#L846">846</a><span class="code-text"><a-p>Prefer American spelling (color, behavior).</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L847" href="#L847">847</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L848" href="#L848">848</a><span class="code-text"><a-p>Default names:</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L849" href="#L849">849</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L850" href="#L850">850</a><span class="code-text"><a-p>* `res` -- &quot;result of the function&quot; local variable</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L851" href="#L851">851</a><span class="code-text"><a-p>* `it` -- I don&#39;t really care about the name</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L852" href="#L852">852</a><span class="code-text"><a-p>* `n_foos` -- number of foos (prefer this to `foo_count`)</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L853" href="#L853">853</a><span class="code-text"><a-p>* `foo_idx` -- index of `foo`</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L854" href="#L854">854</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L855" href="#L855">855</a><span class="code-text"><a-p>Many names in rust-analyzer conflict with keywords.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L856" href="#L856">856</a><span class="code-text"><a-p>We use mangled names instead of `r#ident` syntax:</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L857" href="#L857">857</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L858" href="#L858">858</a><span class="code-text"><a-p>```</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L859" href="#L859">859</a><span class="code-text"><a-p>crate  -&gt; krate</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L860" href="#L860">860</a><span class="code-text"><a-p>enum   -&gt; enum_</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L861" href="#L861">861</a><span class="code-text"><a-p>fn     -&gt; func</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L862" href="#L862">862</a><span class="code-text"><a-p>impl   -&gt; imp</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L863" href="#L863">863</a><span class="code-text"><a-p>macro  -&gt; mac</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L864" href="#L864">864</a><span class="code-text"><a-p>mod    -&gt; module</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L865" href="#L865">865</a><span class="code-text"><a-p>struct -&gt; strukt</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L866" href="#L866">866</a><span class="code-text"><a-p>trait  -&gt; trait_</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L867" href="#L867">867</a><span class="code-text"><a-p>type   -&gt; ty</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L868" href="#L868">868</a><span class="code-text"><a-p>```</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L869" href="#L869">869</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L870" href="#L870">870</a><span class="code-text"><a-p>**Rationale:** consistency.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L871" href="#L871">871</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L872" href="#L872">872</a><span class="code-text"><a-p>## </a-p><a-tt>Early Returns</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L873" href="#L873">873</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L874" href="#L874">874</a><span class="code-text"><a-p>Do use early returns</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L875" href="#L875">875</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L876" href="#L876">876</a><span class="code-text"><a-p>```</a-p><a-tl>rust</a-tl></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L877" href="#L877">877</a><span class="code-text"><a-p>// GOOD</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L878" href="#L878">878</a><span class="code-text"><a-p>fn </a-p><a-f>foo</a-f><a-p>() -&gt; </a-p><a-t>Option</a-t><a-p>&lt;</a-p><a-t>Bar</a-t><a-p>&gt; {</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L879" href="#L879">879</a><span class="code-text"><a-p>    </a-p><a-k>if</a-k><a-p> !</a-p><a-f>condition</a-f><a-p>() {</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L880" href="#L880">880</a><span class="code-text"><a-p>        </a-p><a-k>return</a-k><a-p> </a-p><a-cr>None</a-cr><a-p>;</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L881" href="#L881">881</a><span class="code-text"><a-p>    }</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L882" href="#L882">882</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L883" href="#L883">883</a><span class="code-text"><a-p>    </a-p><a-f>Some</a-f><a-p>(...</a-p><a-pr>)</a-pr></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L884" href="#L884">884</a><span class="code-text"><a-p>}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L885" href="#L885">885</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L886" href="#L886">886</a><span class="code-text"><a-p>// BAD</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L887" href="#L887">887</a><span class="code-text"><a-p>fn </a-p><a-f>foo</a-f><a-p>() -&gt; </a-p><a-t>Option</a-t><a-p>&lt;</a-p><a-t>Bar</a-t><a-p>&gt; {</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L888" href="#L888">888</a><span class="code-text"><a-p>    </a-p><a-k>if</a-k><a-p> </a-p><a-f>condition</a-f><a-p>() {</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L889" href="#L889">889</a><span class="code-text"><a-p>        </a-p><a-f>Some</a-f><a-p>(...</a-p><a-pr>)</a-pr></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L890" href="#L890">890</a><span class="code-text"><a-p>    } </a-p><a-k>else</a-k><a-p> {</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L891" href="#L891">891</a><span class="code-text"><a-p>        </a-p><a-cr>None</a-cr></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L892" href="#L892">892</a><span class="code-text"><a-p>    }</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L893" href="#L893">893</a><span class="code-text"><a-p>}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L894" href="#L894">894</a><span class="code-text"><a-p>```</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L895" href="#L895">895</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L896" href="#L896">896</a><span class="code-text"><a-p>**Rationale:** reduce cognitive stack usage.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L897" href="#L897">897</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L898" href="#L898">898</a><span class="code-text"><a-p>Use `return Err(err)` to throw an error:</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L899" href="#L899">899</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L900" href="#L900">900</a><span class="code-text"><a-p>```</a-p><a-tl>rust</a-tl></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L901" href="#L901">901</a><span class="code-text"><a-p>// GOOD</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L902" href="#L902">902</a><span class="code-text"><a-p>fn </a-p><a-f>f</a-f><a-p>() -&gt; </a-p><a-t>Result</a-t><a-p>&lt;(), ()&gt; {</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L903" href="#L903">903</a><span class="code-text"><a-p>    </a-p><a-k>if</a-k><a-p> condition {</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L904" href="#L904">904</a><span class="code-text"><a-p>        </a-p><a-k>return</a-k><a-p> </a-p><a-f>Err</a-f><a-p>(());</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L905" href="#L905">905</a><span class="code-text"><a-p>    }</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L906" href="#L906">906</a><span class="code-text"><a-p>    </a-p><a-f>Ok</a-f><a-p>(())</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L907" href="#L907">907</a><span class="code-text"><a-p>}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L908" href="#L908">908</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L909" href="#L909">909</a><span class="code-text"><a-p>// BAD</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L910" href="#L910">910</a><span class="code-text"><a-p>fn </a-p><a-f>f</a-f><a-p>() -&gt; </a-p><a-t>Result</a-t><a-p>&lt;(), ()&gt; {</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L911" href="#L911">911</a><span class="code-text"><a-p>    </a-p><a-k>if</a-k><a-p> condition {</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L912" href="#L912">912</a><span class="code-text"><a-p>        </a-p><a-f>Err</a-f><a-p>(())?;</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L913" href="#L913">913</a><span class="code-text"><a-p>    }</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L914" href="#L914">914</a><span class="code-text"><a-p>    </a-p><a-f>Ok</a-f><a-p>(())</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L915" href="#L915">915</a><span class="code-text"><a-p>}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L916" href="#L916">916</a><span class="code-text"><a-p>```</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L917" href="#L917">917</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L918" href="#L918">918</a><span class="code-text"><a-p>**Rationale:** `return` has type `!`, which allows the compiler to flag dead</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L919" href="#L919">919</a><span class="code-text"><a-p>code (`Err(...)?` is of unconstrained generic type `T`).</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L920" href="#L920">920</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L921" href="#L921">921</a><span class="code-text"><a-p>## </a-p><a-tt>Comparisons</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L922" href="#L922">922</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L923" href="#L923">923</a><span class="code-text"><a-p>When doing multiple comparisons use `&lt;`/`&lt;=`, avoid `&gt;`/`&gt;=`.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L924" href="#L924">924</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L925" href="#L925">925</a><span class="code-text"><a-p>```</a-p><a-tl>rust</a-tl></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L926" href="#L926">926</a><span class="code-text"><a-p>// GOOD</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L927" href="#L927">927</a><span class="code-text"><a-p>assert!(lo &lt;= x &amp;&amp; x &lt;= hi);</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L928" href="#L928">928</a><span class="code-text"><a-p>assert!(r1 &lt; l2 || r2 &lt; l1);</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L929" href="#L929">929</a><span class="code-text"><a-p>assert!(x &lt; y);</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L930" href="#L930">930</a><span class="code-text"><a-p>assert!(</a-p><a-co>0</a-co><a-p> &lt; x);</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L931" href="#L931">931</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L932" href="#L932">932</a><span class="code-text"><a-p>// BAD</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L933" href="#L933">933</a><span class="code-text"><a-p>assert!(x &gt;= lo &amp;&amp; x &lt;= hi);</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L934" href="#L934">934</a><span class="code-text"><a-p>assert!(r1 &lt; l2 || l1 &gt; r2);</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L935" href="#L935">935</a><span class="code-text"><a-p>assert!(y &gt; x);</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L936" href="#L936">936</a><span class="code-text"><a-p>assert!(x &gt; </a-p><a-co>0</a-co><a-p>);</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L937" href="#L937">937</a><span class="code-text"><a-p>```</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L938" href="#L938">938</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L939" href="#L939">939</a><span class="code-text"><a-p>**Rationale:** Less-then comparisons are more intuitive, they correspond spatially to [real line](https://en.wikipedia.org/wiki/Real_line).</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L940" href="#L940">940</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L941" href="#L941">941</a><span class="code-text"><a-p>## </a-p><a-tt>If-let</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L942" href="#L942">942</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L943" href="#L943">943</a><span class="code-text"><a-p>Avoid `if let ... { } else { }` construct, use `match` instead.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L944" href="#L944">944</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L945" href="#L945">945</a><span class="code-text"><a-p>```</a-p><a-tl>rust</a-tl></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L946" href="#L946">946</a><span class="code-text"><a-p>// GOOD</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L947" href="#L947">947</a><span class="code-text"><a-p>match ctx.</a-p><a-pr>expected_type</a-pr><a-p>.</a-p><a-f>as_ref</a-f><a-p>() {</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L948" href="#L948">948</a><span class="code-text"><a-p>    </a-p><a-cr>Some</a-cr><a-p>(expected_type) =&gt; completion_ty == expected_type &amp;&amp; !expected_type.</a-p><a-f>is_unit</a-f><a-p>(),</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L949" href="#L949">949</a><span class="code-text"><a-p>    </a-p><a-cr>None</a-cr><a-p> =&gt; </a-p><a-co>false</a-co><a-p>,</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L950" href="#L950">950</a><span class="code-text"><a-p>}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L951" href="#L951">951</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L952" href="#L952">952</a><span class="code-text"><a-p>// BAD</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L953" href="#L953">953</a><span class="code-text"><a-p>if </a-p><a-k>let</a-k><a-p> </a-p><a-cr>Some</a-cr><a-p>(expected_type) = ctx.</a-p><a-pr>expected_type</a-pr><a-p>.</a-p><a-f>as_ref</a-f><a-p>() {</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L954" href="#L954">954</a><span class="code-text"><a-p>    completion_ty == expected_type &amp;&amp; !expected_type.</a-p><a-f>is_unit</a-f><a-p>()</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L955" href="#L955">955</a><span class="code-text"><a-p>} </a-p><a-k>else</a-k><a-p> {</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L956" href="#L956">956</a><span class="code-text"><a-p>    </a-p><a-co>false</a-co></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L957" href="#L957">957</a><span class="code-text"><a-p>}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L958" href="#L958">958</a><span class="code-text"><a-p>```</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L959" href="#L959">959</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L960" href="#L960">960</a><span class="code-text"><a-p>**Rationale:** `match` is almost always more compact.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L961" href="#L961">961</a><span class="code-text"><a-p>The `else` branch can get a more precise pattern: `None` or `Err(_)` instead of `_`.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L962" href="#L962">962</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L963" href="#L963">963</a><span class="code-text"><a-p>## </a-p><a-tt>Match Ergonomics</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L964" href="#L964">964</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L965" href="#L965">965</a><span class="code-text"><a-p>Don&#39;t use the `ref` keyword.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L966" href="#L966">966</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L967" href="#L967">967</a><span class="code-text"><a-p>**Rationale:** consistency &amp; simplicity.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L968" href="#L968">968</a><span class="code-text"><a-p>`ref` was required before [match ergonomics](https://github.com/rust-lang/rfcs/blob/master/text/2005-match-ergonomics.md).</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L969" href="#L969">969</a><span class="code-text"><a-p>Today, it is redundant.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L970" href="#L970">970</a><span class="code-text"><a-p>Between `ref` and mach ergonomics, the latter is more ergonomic in most cases, and is simpler (does not require a keyword).</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L971" href="#L971">971</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L972" href="#L972">972</a><span class="code-text"><a-p>## </a-p><a-tt>Empty Match Arms</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L973" href="#L973">973</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L974" href="#L974">974</a><span class="code-text"><a-p>Use `=&gt; (),` when a match arm is intentionally empty:</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L975" href="#L975">975</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L976" href="#L976">976</a><span class="code-text"><a-p>```</a-p><a-tl>rust</a-tl></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L977" href="#L977">977</a><span class="code-text"><a-p>// GOOD</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L978" href="#L978">978</a><span class="code-text"><a-p>match result {</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L979" href="#L979">979</a><span class="code-text"><a-p>    </a-p><a-cr>Ok</a-cr><a-p>(_) =&gt; (),</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L980" href="#L980">980</a><span class="code-text"><a-p>    </a-p><a-cr>Err</a-cr><a-p>(err) =&gt; </a-p><a-m>error!</a-m><a-p>(</a-p><a-s>&quot;{}&quot;</a-s><a-p>, err),</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L981" href="#L981">981</a><span class="code-text"><a-p>}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L982" href="#L982">982</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L983" href="#L983">983</a><span class="code-text"><a-p>// BAD</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L984" href="#L984">984</a><span class="code-text"><a-p>match result {</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L985" href="#L985">985</a><span class="code-text"><a-p>    </a-p><a-cr>Ok</a-cr><a-p>(_) =&gt; {}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L986" href="#L986">986</a><span class="code-text"><a-p>    </a-p><a-cr>Err</a-cr><a-p>(err) =&gt; </a-p><a-m>error!</a-m><a-p>(</a-p><a-s>&quot;{}&quot;</a-s><a-p>, err),</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L987" href="#L987">987</a><span class="code-text"><a-p>}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L988" href="#L988">988</a><span class="code-text"><a-p>```</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L989" href="#L989">989</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L990" href="#L990">990</a><span class="code-text"><a-p>**Rationale:** consistency.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L991" href="#L991">991</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L992" href="#L992">992</a><span class="code-text"><a-p>## </a-p><a-tt>Functional Combinators</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L993" href="#L993">993</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L994" href="#L994">994</a><span class="code-text"><a-p>Use high order monadic combinators like `map`, `then` when they are a natural choice; don&#39;t bend the code to fit into some combinator.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L995" href="#L995">995</a><span class="code-text"><a-p>If writing a chain of combinators creates friction, replace them with control flow constructs: `for`, `if`, `match`.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L996" href="#L996">996</a><span class="code-text"><a-p>Mostly avoid `bool::then` and `Option::filter`.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L997" href="#L997">997</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L998" href="#L998">998</a><span class="code-text"><a-p>```</a-p><a-tl>rust</a-tl></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L999" href="#L999">999</a><span class="code-text"><a-p>// GOOD</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1000" href="#L1000">1000</a><span class="code-text"><a-p>if !x.</a-p><a-f>cond</a-f><a-p>() {</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1001" href="#L1001">1001</a><span class="code-text"><a-p>    </a-p><a-k>return</a-k><a-p> </a-p><a-cr>None</a-cr><a-p>;</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1002" href="#L1002">1002</a><span class="code-text"><a-p>}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1003" href="#L1003">1003</a><span class="code-text"><a-p>Some(x)</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1004" href="#L1004">1004</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1005" href="#L1005">1005</a><span class="code-text"><a-p>// BAD</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1006" href="#L1006">1006</a><span class="code-text"><a-p>Some(x).</a-p><a-f>filter</a-f><a-p>(|it| it.</a-p><a-f>cond</a-f><a-p>())</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1007" href="#L1007">1007</a><span class="code-text"><a-p>```</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1008" href="#L1008">1008</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1009" href="#L1009">1009</a><span class="code-text"><a-p>This rule is more &quot;soft&quot; then others, and boils down mostly to taste.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1010" href="#L1010">1010</a><span class="code-text"><a-p>The guiding principle behind this rule is that code should be dense in computation, and sparse in the number of expressions per line.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1011" href="#L1011">1011</a><span class="code-text"><a-p>The second example contains *less* computation -- the `filter` function is an indirection for `if`, it doesn&#39;t do any useful work by itself.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1012" href="#L1012">1012</a><span class="code-text"><a-p>At the same time, it is more crowded -- it takes more time to visually scan it.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1013" href="#L1013">1013</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1014" href="#L1014">1014</a><span class="code-text"><a-p>**Rationale:** consistency, playing to language&#39;s strengths.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1015" href="#L1015">1015</a><span class="code-text"><a-p>Rust has first-class support for imperative control flow constructs like `for` and `if`, while functions are less first-class due to lack of universal function type, currying, and non-first-class effects (`?`, `.await`).</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1016" href="#L1016">1016</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1017" href="#L1017">1017</a><span class="code-text"><a-p>## </a-p><a-tt>Turbofish</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1018" href="#L1018">1018</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1019" href="#L1019">1019</a><span class="code-text"><a-p>Prefer type ascription over the turbofish.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1020" href="#L1020">1020</a><span class="code-text"><a-p>When ascribing types, avoid `_`</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1021" href="#L1021">1021</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1022" href="#L1022">1022</a><span class="code-text"><a-p>```</a-p><a-tl>rust</a-tl></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1023" href="#L1023">1023</a><span class="code-text"><a-p>// GOOD</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1024" href="#L1024">1024</a><span class="code-text"><a-p>let mutable: </a-p><a-t>Vec</a-t><a-p>&lt;</a-p><a-t>T</a-t><a-p>&gt; = old.</a-p><a-f>into_iter</a-f><a-p>().</a-p><a-f>map</a-f><a-p>(|it| builder.</a-p><a-f>make_mut</a-f><a-p>(it)).</a-p><a-f>collect</a-f><a-p>();</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1025" href="#L1025">1025</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1026" href="#L1026">1026</a><span class="code-text"><a-p>// BAD</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1027" href="#L1027">1027</a><span class="code-text"><a-p>let mutable: </a-p><a-t>Vec</a-t><a-p>&lt;</a-p><a-t>_</a-t><a-p>&gt; = old.</a-p><a-f>into_iter</a-f><a-p>().</a-p><a-f>map</a-f><a-p>(|it| builder.</a-p><a-f>make_mut</a-f><a-p>(it)).</a-p><a-f>collect</a-f><a-p>();</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1028" href="#L1028">1028</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1029" href="#L1029">1029</a><span class="code-text"><a-p>// BAD</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1030" href="#L1030">1030</a><span class="code-text"><a-p>let mutable = old.</a-p><a-f>into_iter</a-f><a-p>().</a-p><a-f>map</a-f><a-p>(|it| builder.</a-p><a-f>make_mut</a-f><a-p>(it)).</a-p><a-f>collect</a-f><a-p>::&lt;</a-p><a-t>Vec</a-t><a-p>&lt;</a-p><a-t>_</a-t><a-p>&gt;&gt;();</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1031" href="#L1031">1031</a><span class="code-text"><a-p>```</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1032" href="#L1032">1032</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1033" href="#L1033">1033</a><span class="code-text"><a-p>**Rationale:** consistency, readability.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1034" href="#L1034">1034</a><span class="code-text"><a-p>If compiler struggles to infer the type, the human would as well.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1035" href="#L1035">1035</a><span class="code-text"><a-p>Having the result type specified up-front helps with understanding what the chain of iterator methods is doing.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1036" href="#L1036">1036</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1037" href="#L1037">1037</a><span class="code-text"><a-p>## </a-p><a-tt>Helper Functions</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1038" href="#L1038">1038</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1039" href="#L1039">1039</a><span class="code-text"><a-p>Avoid creating single-use helper functions:</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1040" href="#L1040">1040</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1041" href="#L1041">1041</a><span class="code-text"><a-p>```</a-p><a-tl>rust</a-tl></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1042" href="#L1042">1042</a><span class="code-text"><a-p>// GOOD</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1043" href="#L1043">1043</a><span class="code-text"><a-p>let buf = {</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1044" href="#L1044">1044</a><span class="code-text"><a-p>    </a-p><a-k>let</a-k><a-p> </a-p><a-k>mut</a-k><a-p> buf = </a-p><a-f>get_empty_buf</a-f><a-p>(</a-p><a-o>&amp;</a-o><a-k>mut</a-k><a-p> arena);</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1045" href="#L1045">1045</a><span class="code-text"><a-p>    buf.</a-p><a-f>add_item</a-f><a-p>(item);</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1046" href="#L1046">1046</a><span class="code-text"><a-p>    buf</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1047" href="#L1047">1047</a><span class="code-text"><a-p>};</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1048" href="#L1048">1048</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1049" href="#L1049">1049</a><span class="code-text"><a-p>// BAD</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1050" href="#L1050">1050</a><span class="code-text"><a-p>let buf = </a-p><a-f>prepare_buf</a-f><a-p>(</a-p><a-o>&amp;</a-o><a-k>mut</a-k><a-p> arena, item);</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1051" href="#L1051">1051</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1052" href="#L1052">1052</a><span class="code-text"><a-p>...</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1053" href="#L1053">1053</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1054" href="#L1054">1054</a><span class="code-text"><a-p>fn </a-p><a-f>prepare_buf</a-f><a-p>(arena: </a-p><a-o>&amp;</a-o><a-p>mut </a-p><a-cr>Arena</a-cr><a-p>, item: </a-p><a-cr>Item</a-cr><a-p>) -&gt; </a-p><a-cr>ItemBuf</a-cr><a-p> {</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1055" href="#L1055">1055</a><span class="code-text"><a-p>    let mut res = </a-p><a-f>get_empty_buf</a-f><a-p>(</a-p><a-o>&amp;</a-o><a-k>mut</a-k><a-p> arena);</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1056" href="#L1056">1056</a><span class="code-text"><a-p>    res.</a-p><a-f>add_item</a-f><a-p>(item);</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1057" href="#L1057">1057</a><span class="code-text"><a-p>    res</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1058" href="#L1058">1058</a><span class="code-text"><a-p>}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1059" href="#L1059">1059</a><span class="code-text"><a-p>```</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1060" href="#L1060">1060</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1061" href="#L1061">1061</a><span class="code-text"><a-p>Exception: if you want to make use of `return` or `?`.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1062" href="#L1062">1062</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1063" href="#L1063">1063</a><span class="code-text"><a-p>**Rationale:** single-use functions change frequently, adding or removing parameters adds churn.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1064" href="#L1064">1064</a><span class="code-text"><a-p>A block serves just as well to delineate a bit of logic, but has access to all the context.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1065" href="#L1065">1065</a><span class="code-text"><a-p>Re-using originally single-purpose function often leads to bad coupling.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1066" href="#L1066">1066</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1067" href="#L1067">1067</a><span class="code-text"><a-p>## </a-p><a-tt>Local Helper Functions</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1068" href="#L1068">1068</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1069" href="#L1069">1069</a><span class="code-text"><a-p>Put nested helper functions at the end of the enclosing functions</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1070" href="#L1070">1070</a><span class="code-text"><a-p>(this requires using return statement).</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1071" href="#L1071">1071</a><span class="code-text"><a-p>Don&#39;t nest more than one level deep.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1072" href="#L1072">1072</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1073" href="#L1073">1073</a><span class="code-text"><a-p>```</a-p><a-tl>rust</a-tl></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1074" href="#L1074">1074</a><span class="code-text"><a-p>// GOOD</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1075" href="#L1075">1075</a><span class="code-text"><a-p>fn </a-p><a-f>dfs</a-f><a-p>(</a-p><a-v>graph</a-v><a-p>: </a-p><a-o>&amp;</a-o><a-t>Graph</a-t><a-p>, </a-p><a-v>v</a-v><a-p>: </a-p><a-t>Vertex</a-t><a-p>) -&gt; </a-p><a-t>usize</a-t><a-p> {</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1076" href="#L1076">1076</a><span class="code-text"><a-p>    </a-p><a-k>let</a-k><a-p> </a-p><a-k>mut</a-k><a-p> visited = </a-p><a-t>FxHashSet</a-t><a-p>::</a-p><a-f>default</a-f><a-p>();</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1077" href="#L1077">1077</a><span class="code-text"><a-p>    </a-p><a-k>return</a-k><a-p> </a-p><a-f>go</a-f><a-p>(graph, </a-p><a-o>&amp;</a-o><a-k>mut</a-k><a-p> visited, v);</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1078" href="#L1078">1078</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1079" href="#L1079">1079</a><span class="code-text"><a-p>    </a-p><a-k>fn</a-k><a-p> </a-p><a-f>go</a-f><a-p>(</a-p><a-v>graph</a-v><a-p>: </a-p><a-o>&amp;</a-o><a-t>Graph</a-t><a-p>, </a-p><a-v>visited</a-v><a-p>: </a-p><a-o>&amp;</a-o><a-k>mut</a-k><a-p> </a-p><a-t>FxHashSet</a-t><a-p>&lt;</a-p><a-t>Vertex</a-t><a-p>&gt;, </a-p><a-v>v</a-v><a-p>: </a-p><a-t>usize</a-t><a-p>) -&gt; </a-p><a-t>usize</a-t><a-p> {</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1080" href="#L1080">1080</a><span class="code-text"><a-p>        ...</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1081" href="#L1081">1081</a><span class="code-text"><a-p>    }</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1082" href="#L1082">1082</a><span class="code-text"><a-p>}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1083" href="#L1083">1083</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1084" href="#L1084">1084</a><span class="code-text"><a-p>// BAD</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1085" href="#L1085">1085</a><span class="code-text"><a-p>fn </a-p><a-f>dfs</a-f><a-p>(</a-p><a-v>graph</a-v><a-p>: </a-p><a-o>&amp;</a-o><a-t>Graph</a-t><a-p>, </a-p><a-v>v</a-v><a-p>: </a-p><a-t>Vertex</a-t><a-p>) -&gt; </a-p><a-t>usize</a-t><a-p> {</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1086" href="#L1086">1086</a><span class="code-text"><a-p>    </a-p><a-k>fn</a-k><a-p> </a-p><a-f>go</a-f><a-p>(</a-p><a-v>graph</a-v><a-p>: </a-p><a-o>&amp;</a-o><a-t>Graph</a-t><a-p>, </a-p><a-v>visited</a-v><a-p>: </a-p><a-o>&amp;</a-o><a-k>mut</a-k><a-p> </a-p><a-t>FxHashSet</a-t><a-p>&lt;</a-p><a-t>Vertex</a-t><a-p>&gt;, </a-p><a-v>v</a-v><a-p>: </a-p><a-t>usize</a-t><a-p>) -&gt; </a-p><a-t>usize</a-t><a-p> {</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1087" href="#L1087">1087</a><span class="code-text"><a-p>        ...</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1088" href="#L1088">1088</a><span class="code-text"><a-p>    }</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1089" href="#L1089">1089</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1090" href="#L1090">1090</a><span class="code-text"><a-p>    </a-p><a-k>let</a-k><a-p> </a-p><a-k>mut</a-k><a-p> visited = </a-p><a-t>FxHashSet</a-t><a-p>::</a-p><a-f>default</a-f><a-p>();</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1091" href="#L1091">1091</a><span class="code-text"><a-p>    </a-p><a-f>go</a-f><a-p>(graph, </a-p><a-o>&amp;</a-o><a-k>mut</a-k><a-p> visited, v)</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1092" href="#L1092">1092</a><span class="code-text"><a-p>}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1093" href="#L1093">1093</a><span class="code-text"><a-p>```</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1094" href="#L1094">1094</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1095" href="#L1095">1095</a><span class="code-text"><a-p>**Rationale:** consistency, improved top-down readability.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1096" href="#L1096">1096</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1097" href="#L1097">1097</a><span class="code-text"><a-p>## </a-p><a-tt>Helper Variables</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1098" href="#L1098">1098</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1099" href="#L1099">1099</a><span class="code-text"><a-p>Introduce helper variables freely, especially for multiline conditions:</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1100" href="#L1100">1100</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1101" href="#L1101">1101</a><span class="code-text"><a-p>```</a-p><a-tl>rust</a-tl></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1102" href="#L1102">1102</a><span class="code-text"><a-p>// GOOD</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1103" href="#L1103">1103</a><span class="code-text"><a-p>let rustfmt_not_installed =</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1104" href="#L1104">1104</a><span class="code-text"><a-p>    captured_stderr.</a-p><a-f>contains</a-f><a-p>(</a-p><a-s>&quot;not installed&quot;</a-s><a-p>) || captured_stderr.</a-p><a-f>contains</a-f><a-p>(</a-p><a-s>&quot;not available&quot;</a-s><a-p>);</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1105" href="#L1105">1105</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1106" href="#L1106">1106</a><span class="code-text"><a-p>match output.</a-p><a-pr>status</a-pr><a-p>.</a-p><a-f>code</a-f><a-p>() {</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1107" href="#L1107">1107</a><span class="code-text"><a-p>    </a-p><a-cr>Some</a-cr><a-p>(</a-p><a-co>1</a-co><a-p>) </a-p><a-k>if</a-k><a-p> !rustfmt_not_installed =&gt; </a-p><a-f>Ok</a-f><a-p>(</a-p><a-cr>None</a-cr><a-p>),</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1108" href="#L1108">1108</a><span class="code-text"><a-p>    _ =&gt; </a-p><a-f>Err</a-f><a-p>(</a-p><a-m>format_err!</a-m><a-p>(</a-p><a-s>&quot;rustfmt failed:\n{}&quot;</a-s><a-p>, captured_stderr)),</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1109" href="#L1109">1109</a><span class="code-text"><a-p>};</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1110" href="#L1110">1110</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1111" href="#L1111">1111</a><span class="code-text"><a-p>// BAD</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1112" href="#L1112">1112</a><span class="code-text"><a-p>match output.</a-p><a-pr>status</a-pr><a-p>.</a-p><a-f>code</a-f><a-p>() {</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1113" href="#L1113">1113</a><span class="code-text"><a-p>    </a-p><a-cr>Some</a-cr><a-p>(</a-p><a-co>1</a-co><a-p>)</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1114" href="#L1114">1114</a><span class="code-text"><a-p>        </a-p><a-k>if</a-k><a-p> !captured_stderr.</a-p><a-f>contains</a-f><a-p>(</a-p><a-s>&quot;not installed&quot;</a-s><a-p>)</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1115" href="#L1115">1115</a><span class="code-text"><a-p>           &amp;&amp; !captured_stderr.</a-p><a-f>contains</a-f><a-p>(</a-p><a-s>&quot;not available&quot;</a-s><a-p>) =&gt; </a-p><a-f>Ok</a-f><a-p>(</a-p><a-cr>None</a-cr><a-p>),</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1116" href="#L1116">1116</a><span class="code-text"><a-p>    _ =&gt; </a-p><a-f>Err</a-f><a-p>(</a-p><a-m>format_err!</a-m><a-p>(</a-p><a-s>&quot;rustfmt failed:\n{}&quot;</a-s><a-p>, captured_stderr)),</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1117" href="#L1117">1117</a><span class="code-text"><a-p>};</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1118" href="#L1118">1118</a><span class="code-text"><a-p>```</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1119" href="#L1119">1119</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1120" href="#L1120">1120</a><span class="code-text"><a-p>**Rationale:** Like blocks, single-use variables are a cognitively cheap abstraction, as they have access to all the context.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1121" href="#L1121">1121</a><span class="code-text"><a-p>Extra variables help during debugging, they make it easy to print/view important intermediate results.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1122" href="#L1122">1122</a><span class="code-text"><a-p>Giving a name to a condition inside an `if` expression often improves clarity and leads to nicely formatted code.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1123" href="#L1123">1123</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1124" href="#L1124">1124</a><span class="code-text"><a-p>## </a-p><a-tt>Token names</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1125" href="#L1125">1125</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1126" href="#L1126">1126</a><span class="code-text"><a-p>Use `T![foo]` instead of `SyntaxKind::FOO_KW`.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1127" href="#L1127">1127</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1128" href="#L1128">1128</a><span class="code-text"><a-p>```</a-p><a-tl>rust</a-tl></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1129" href="#L1129">1129</a><span class="code-text"><a-p>// GOOD</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1130" href="#L1130">1130</a><span class="code-text"><a-p>match p.</a-p><a-f>current</a-f><a-p>() {</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1131" href="#L1131">1131</a><span class="code-text"><a-p>    </a-p><a-m>T!</a-m><a-p>[</a-p><a-co>true</a-co><a-p>] | </a-p><a-m>T!</a-m><a-p>[</a-p><a-co>false</a-co><a-p>] =&gt; </a-p><a-co>true</a-co><a-p>,</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1132" href="#L1132">1132</a><span class="code-text"><a-p>    _ =&gt; </a-p><a-co>false</a-co><a-p>,</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1133" href="#L1133">1133</a><span class="code-text"><a-p>}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1134" href="#L1134">1134</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1135" href="#L1135">1135</a><span class="code-text"><a-p>// BAD</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1136" href="#L1136">1136</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1137" href="#L1137">1137</a><span class="code-text"><a-p>match p.</a-p><a-f>current</a-f><a-p>() {</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1138" href="#L1138">1138</a><span class="code-text"><a-p>    </a-p><a-t>SyntaxKind</a-t><a-p>::</a-p><a-cr>TRUE_KW</a-cr><a-p> | </a-p><a-t>SyntaxKind</a-t><a-p>::</a-p><a-cr>FALSE_KW</a-cr><a-p> =&gt; </a-p><a-co>true</a-co><a-p>,</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1139" href="#L1139">1139</a><span class="code-text"><a-p>    _ =&gt; </a-p><a-co>false</a-co><a-p>,</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1140" href="#L1140">1140</a><span class="code-text"><a-p>}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1141" href="#L1141">1141</a><span class="code-text"><a-p>```</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1142" href="#L1142">1142</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1143" href="#L1143">1143</a><span class="code-text"><a-p>**Rationale:** The macro uses the familiar Rust syntax, avoiding ambiguities like &quot;is this a brace or bracket?&quot;.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1144" href="#L1144">1144</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1145" href="#L1145">1145</a><span class="code-text"><a-p>## </a-p><a-tt>Documentation</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1146" href="#L1146">1146</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1147" href="#L1147">1147</a><span class="code-text"><a-p>Style inline code comments as proper sentences.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1148" href="#L1148">1148</a><span class="code-text"><a-p>Start with a capital letter, end with a dot.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1149" href="#L1149">1149</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1150" href="#L1150">1150</a><span class="code-text"><a-p>```</a-p><a-tl>rust</a-tl></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1151" href="#L1151">1151</a><span class="code-text"><a-p>// GOOD</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1152" href="#L1152">1152</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1153" href="#L1153">1153</a><span class="code-text"><a-p>// Only simple single segment paths are allowed.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1154" href="#L1154">1154</a><span class="code-text"><a-p>MergeBehavior::</a-p><a-cr>Last</a-cr><a-p> =&gt; {</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1155" href="#L1155">1155</a><span class="code-text"><a-p>    tree.</a-p><a-f>use_tree_list</a-f><a-p>().</a-p><a-f>is_none</a-f><a-p>() &amp;&amp; tree.</a-p><a-f>path</a-f><a-p>().</a-p><a-f>map</a-f><a-p>(path_len) &lt;= </a-p><a-f>Some</a-f><a-p>(</a-p><a-co>1</a-co><a-p>)</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1156" href="#L1156">1156</a><span class="code-text"><a-p>}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1157" href="#L1157">1157</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1158" href="#L1158">1158</a><span class="code-text"><a-p>// BAD</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1159" href="#L1159">1159</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1160" href="#L1160">1160</a><span class="code-text"><a-p>// only simple single segment paths are allowed</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1161" href="#L1161">1161</a><span class="code-text"><a-p>MergeBehavior::</a-p><a-cr>Last</a-cr><a-p> =&gt; {</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1162" href="#L1162">1162</a><span class="code-text"><a-p>    tree.</a-p><a-f>use_tree_list</a-f><a-p>().</a-p><a-f>is_none</a-f><a-p>() &amp;&amp; tree.</a-p><a-f>path</a-f><a-p>().</a-p><a-f>map</a-f><a-p>(path_len) &lt;= </a-p><a-f>Some</a-f><a-p>(</a-p><a-co>1</a-co><a-p>)</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1163" href="#L1163">1163</a><span class="code-text"><a-p>}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1164" href="#L1164">1164</a><span class="code-text"><a-p>```</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1165" href="#L1165">1165</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1166" href="#L1166">1166</a><span class="code-text">**Rationale:** writing a sentence (or maybe even a paragraph) rather just &quot;a comment&quot; creates a more appropriate frame of mind.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1167" href="#L1167">1167</a><span class="code-text">It tricks you into writing down more of the context you keep in your head while coding.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1168" href="#L1168">1168</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1169" href="#L1169">1169</a><span class="code-text">For `.md` and `.adoc` files, prefer a sentence-per-line format, don&#39;t wrap lines.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1170" href="#L1170">1170</a><span class="code-text">If the line is too long, you want to split the sentence in two :-)</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1171" href="#L1171">1171</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1172" href="#L1172">1172</a><span class="code-text">**Rationale:** much easier to edit the text and read the diff, see [this link](https://asciidoctor.org/docs/asciidoc-recommended-practices/#one-sentence-per-line).</span></span></pre></div></div>
</main>
</body>
</html>
