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 moving towards the [Rust standard coding style][fmt].
  11 This is enforced by the "tidy" script and can be mostly
  12 automated using `./x.py fmt`.
  13
  14 As the output of [rustfmt] is not completely stable,
  15 formatting this repository using `cargo fmt` is not recommended.
  16
  17 The tidy script runs automatically when you do `./x.py test` and can be run
  18 in isolation with `./x.py test tidy`.
  19
  20 [fmt]: https://github.com/rust-dev-tools/fmt-rfcs
  21 [rustfmt]:https://github.com/rust-lang/rustfmt
  22
  23 <a name="copyright"></a>
  24
  25 ### Copyright notice
  26
  27 In the past, files began with a copyright and license notice. Please **omit**
  28 this notice for new files licensed under the standard terms (dual
  29 MIT/Apache-2.0).
  30
  31 All of the copyright notices should be gone by now, but if you come across one
  32 in the rust-lang/rust repo, feel free to open a PR to remove it.
  33
  34 ## Line length
  35
  36 Lines should be at most 100 characters. It's even better if you can
  37 keep things to 80.
  38
  39 **Ignoring the line length limit.** Sometimes – in particular for
  40 tests – it can be necessary to exempt yourself from this limit. In
  41 that case, you can add a comment towards the top of the file like so:
  42
  43 ```rust
  44 // ignore-tidy-linelength
  45 ```
  46
  47 ## Tabs vs spaces
  48
  49 Prefer 4-space indent.
  50
  51 <a name="cc"></a>
  52
  53 # Coding for correctness
  54
  55 Beyond formatting, there are a few other tips that are worth
  56 following.
  57
  58 ## Prefer exhaustive matches
  59
  60 Using `_` in a match is convenient, but it means that when new
  61 variants are added to the enum, they may not get handled correctly.
  62 Ask yourself: if a new variant were added to this enum, what's the
  63 chance that it would want to use the `_` code, versus having some
  64 other treatment?  Unless the answer is "low", then prefer an
  65 exhaustive match. (The same advice applies to `if let` and `while
  66 let`, which are effectively tests for a single variant.)
  67
  68 ## Use "TODO" comments for things you don't want to forget
  69
  70 As a useful tool to yourself, you can insert a `// TODO` comment
  71 for something that you want to get back to before you land your PR:
  72
  73 ```rust,ignore
  74 fn do_something() {
  75     if something_else {
  76         unimplemented!(); // TODO write this
  77     }
  78 }
  79 ```
  80
  81 The tidy script will report an error for a `// TODO` comment, so this
  82 code would not be able to land until the TODO is fixed (or removed).
  83
  84 This can also be useful in a PR as a way to signal from one commit that you are
  85 leaving a bug that a later commit will fix:
  86
  87 ```rust,ignore
  88 if foo {
  89     return true; // TODO wrong, but will be fixed in a later commit
  90 }
  91 ```
  92
  93 <a name="cio"></a>
  94
  95 # Using crates from crates.io
  96
  97 It is allowed to use crates from crates.io, though external
  98 dependencies should not be added gratuitously. All such crates must
  99 have a suitably permissive license. There is an automatic check which
 100 inspects the Cargo metadata to ensure this.
 101
 102 <a name="er"></a>
 103
 104 # How to structure your PR
 105
 106 How you prepare the commits in your PR can make a big difference for the
 107 reviewer.  Here are some tips.
 108
 109 **Isolate "pure refactorings" into their own commit.** For example, if
 110 you rename a method, then put that rename into its own commit, along
 111 with the renames of all the uses.
 112
 113 **More commits is usually better.** If you are doing a large change,
 114 it's almost always better to break it up into smaller steps that can
 115 be independently understood. The one thing to be aware of is that if
 116 you introduce some code following one strategy, then change it
 117 dramatically (versus adding to it) in a later commit, that
 118 'back-and-forth' can be confusing.
 119
 120 **Format liberally.** While only the final commit of a PR must be correctly
 121 formatted, it is both easier to review and less noisy to format each commit
 122 individually using `./x.py fmt`.
 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