src/doc/rustc-dev-guide/src/conventions.md

   1 This file offers some tips on the coding conventions for rustc.  This
   2 chapter covers [formatting](#formatting), [coding for correctness](#cc),
   3 [using crates from crates.io](#cio), and some tips on
   4 [structuring your PR for easy review](#er).
   5
   6 <a name="formatting"></a>
   7
   8 # Formatting and the tidy script
   9
  10 rustc is slowly moving towards the [Rust standard coding style][fmt];
  11 at the moment, however, it follows a rather more *chaotic* style.  We
  12 do have some mandatory formatting conventions, which are automatically
  13 enforced by a script we affectionately call the "tidy" script.  The
  14 tidy script runs automatically when you do `./x.py test` and can be run
  15 in isolation with `./x.py test tidy`.
  16
  17 [fmt]: https://github.com/rust-dev-tools/fmt-rfcs
  18
  19 <a name="copyright"></a>
  20
  21 ### Copyright notice
  22
  23 In the past, files began with a copyright and license notice. Please **omit**
  24 this notice for new files licensed under the standard terms (dual
  25 MIT/Apache-2.0).
  26
  27 All of the copyright notices should be gone by now, but if you come across one
  28 in the rust-lang/rust repo, feel free to open a PR to remove it.
  29
  30 ## Line length
  31
  32 Lines should be at most 100 characters. It's even better if you can
  33 keep things to 80.
  34
  35 **Ignoring the line length limit.** Sometimes – in particular for
  36 tests – it can be necessary to exempt yourself from this limit. In
  37 that case, you can add a comment towards the top of the file (after
  38 the copyright notice) like so:
  39
  40 ```rust
  41 // ignore-tidy-linelength
  42 ```
  43
  44 ## Tabs vs spaces
  45
  46 Prefer 4-space indent.
  47
  48 <a name="cc"></a>
  49
  50 # Coding for correctness
  51
  52 Beyond formatting, there are a few other tips that are worth
  53 following.
  54
  55 ## Prefer exhaustive matches
  56
  57 Using `_` in a match is convenient, but it means that when new
  58 variants are added to the enum, they may not get handled correctly.
  59 Ask yourself: if a new variant were added to this enum, what's the
  60 chance that it would want to use the `_` code, versus having some
  61 other treatment?  Unless the answer is "low", then prefer an
  62 exhaustive match. (The same advice applies to `if let` and `while
  63 let`, which are effectively tests for a single variant.)
  64
  65 ## Use "TODO" comments for things you don't want to forget
  66
  67 As a useful tool to yourself, you can insert a `// TODO` comment
  68 for something that you want to get back to before you land your PR:
  69
  70 ```rust,ignore
  71 fn do_something() {
  72     if something_else {
  73         unimplemented!(); // TODO write this
  74     }
  75 }
  76 ```
  77
  78 The tidy script will report an error for a `// TODO` comment, so this
  79 code would not be able to land until the TODO is fixed (or removed).
  80
  81 This can also be useful in a PR as a way to signal from one commit that you are
  82 leaving a bug that a later commit will fix:
  83
  84 ```rust,ignore
  85 if foo {
  86     return true; // TODO wrong, but will be fixed in a later commit
  87 }
  88 ```
  89
  90 <a name="cio"></a>
  91
  92 # Using crates from crates.io
  93
  94 It is allowed to use crates from crates.io, though external
  95 dependencies should not be added gratuitously. All such crates must
  96 have a suitably permissive license. There is an automatic check which
  97 inspects the Cargo metadata to ensure this.
  98
  99 <a name="er"></a>
 100
 101 # How to structure your PR
 102
 103 How you prepare the commits in your PR can make a big difference for the
 104 reviewer.  Here are some tips.
 105
 106 **Isolate "pure refactorings" into their own commit.** For example, if
 107 you rename a method, then put that rename into its own commit, along
 108 with the renames of all the uses.
 109
 110 **More commits is usually better.** If you are doing a large change,
 111 it's almost always better to break it up into smaller steps that can
 112 be independently understood. The one thing to be aware of is that if
 113 you introduce some code following one strategy, then change it
 114 dramatically (versus adding to it) in a later commit, that
 115 'back-and-forth' can be confusing.
 116
 117 **Only run rustfmt on new content.** One day, we might enforce formatting
 118 for the rust-lang/rust repo. Meanwhile, we prefer that rustfmt not be run
 119 on existing code as that will generate large diffs and will make git blame
 120 harder to sift through. However, running `rustfmt` on new content, e.g. a
 121 new file or a largely new part of a file is ok. Small formatting adjustments
 122 nearby code you are already changing for other purposes are also ok.
 123
 124 **No merges.** We do not allow merge commits into our history, other
 125 than those by bors. If you get a merge conflict, rebase instead via a
 126 command like `git rebase -i rust-lang/master` (presuming you use the
 127 name `rust-lang` for your remote).
 128
 129 **Individual commits do not have to build (but it's nice).** We do not
 130 require that every intermediate commit successfully builds – we only
 131 expect to be able to bisect at a PR level. However, if you *can* make
 132 individual commits build, that is always helpful.
 133
 134 # Naming conventions
 135
 136 Apart from normal Rust style/naming conventions, there are also some specific
 137 to the compiler.
 138
 139 - `cx` tends to be short for "context" and is often used as a suffix. For
 140   example, `tcx` is a common name for the [Typing Context][tcx].
 141
 142 - [`'tcx`][tcx] is used as the lifetime name for the Typing Context.
 143
 144 - Because `crate` is a keyword, if you need a variable to represent something
 145   crate-related, often the spelling is changed to `krate`.
 146
 147 [tcx]: ./ty.md