1# Coding conventions23This chapter covers [formatting](#formatting), [coding for correctness](#cc),4[using crates from crates.io](#cio), and some tips on [structuring your PR for easy review](#er).56<a id="formatting"></a>78## Formatting and the tidy script910rustc is moving towards the [Rust standard coding style][fmt].1112However, for now we don't use stable `rustfmt`; we use a pinned version with a13special config, so this may result in different style from normal [`rustfmt`].14Therefore, formatting this repository using `cargo fmt` is not recommended.1516Instead, formatting should be done using `./x fmt`.17It's a good habit to run `./x fmt` before every commit, as this reduces conflicts later.1819Formatting is checked by the `tidy` script.20It runs automatically when you do `./x test` and can be run in isolation with `./x fmt --check`.2122> **Note: Formatting and test suites**23>24> Most Rust source files under `tests/` directory are not formatted for reasons25> such as whitespace sensitivity, nature of snapshot tests, location-sensitive26> comments and more.27>28> Consult the `ignore` entries in29> <https://github.com/rust-lang/rust/blob/main/rustfmt.toml> for which test30> files are not formatted.3132If you want to use format-on-save in your editor, the pinned version of33`rustfmt` is built under `build/<target>/stage0/bin/rustfmt`.3435[fmt]: https://github.com/rust-dev-tools/fmt-rfcs36[`rustfmt`]:https://github.com/rust-lang/rustfmt3738### Formatting C++ code3940The compiler contains some C++ code for interfacing with parts of LLVM that41don't have a stable C API.42When modifying that code, use this command to format it:4344```console45./x test tidy --extra-checks cpp:fmt --bless46```4748This uses a pinned version of `clang-format`, to avoid relying on the local environment.4950### Formatting and linting Python code5152The Rust repository contains quite a lot of Python code.53We try to keep it both linted and formatted by the [ruff] tool.5455When modifying Python code, use this command to format it:5657```console58./x test tidy --extra-checks py:fmt --bless59```6061And, the following command to run lints:6263```console64./x test tidy --extra-checks py:lint65```6667These use a pinned version of `ruff`, to avoid relying on the local environment.6869[ruff]: https://github.com/astral-sh/ruff7071<a id="copyright"></a>7273<!-- REUSE-IgnoreStart -->74<!-- Prevent REUSE from interpreting the heading as a copyright notice -->75### Copyright notice76<!-- REUSE-IgnoreEnd -->7778In the past, files began with a copyright and license notice.79Please **omit** this notice for new files licensed under the standard terms (MIT OR Apache-2.0).8081All of the copyright notices should be gone by now, but if you come across one82in the rust-lang/rust repo, feel free to open a PR to remove it.8384### Line length8586Lines should be at most 100 characters.87It's even better if you can keep things to 80.8889Sometimes, and particularly for tests, it can be necessary to exempt yourself from this limit.90In that case, you can add a comment towards the top of the file like so:9192```rust93// ignore-tidy-linelength94```9596### Tabs vs spaces9798Prefer 4-space indents.99100<a id="cc"></a>101102## Coding for correctness103104Beyond formatting, there are a few other tips that are worth following.105106### Prefer exhaustive matches107108Using `_` in a match is convenient, but it means that when new109variants are added to the enum, they may not get handled correctly.110Ask yourself: if a new variant were added to this enum, what's the111chance that it would want to use the `_` code, versus having some other treatment?112Unless the answer is "low", then prefer an exhaustive match.113114The same advice applies to `if let` and `while let`,115which are effectively tests for a single variant.116117### Use "TODO" comments for things you don't want to forget118119As a useful tool to yourself, you can insert a `// TODO` comment120for something that you want to get back to before you land your PR:121122```rust,ignore123fn do_something() {124    if something_else {125        unimplemented!(); // TODO write this126    }127}128```129130The tidy script will report an error for a `// TODO` comment, so this131code would not be able to land until the TODO is fixed (or removed).132133This can also be useful in a PR as a way to signal from one commit that you are134leaving a bug that a later commit will fix:135136```rust,ignore137if foo {138    return true; // TODO wrong, but will be fixed in a later commit139}140```141142If you want to leave a note in the codebase, use `// FIXME` instead.143144<a id="cio"></a>145146## Using crates from crates.io147148See the [crates.io dependencies][crates] section.149150<a id="er"></a>151152## How to structure your PR153154How you prepare the commits in your PR can make a big difference for the reviewer.155Here are some tips.156157**Isolate "pure refactorings" into their own commit.** For example, if158you rename a method, then put that rename into its own commit, along159with the renames of all the uses.160161**More commits is usually better.** If you are doing a large change,162it's almost always better to break it up into smaller steps that can be independently understood.163The one thing to be aware of is that if164you introduce some code following one strategy, then change it165dramatically (versus adding to it) in a later commit, that 'back-and-forth' can be confusing.166167**Format liberally.** While only the final commit of a PR must be correctly168formatted, it is both easier to review and less noisy to format each commit169individually using `./x fmt`.170171**No merges.** We do not allow merge commits into our history, other than those by bors.172If you get a merge conflict, rebase instead via a173command like `git rebase --interactive rust-lang/main` (presuming you use the174name `rust-lang` for your remote).175176**Individual commits do not have to build (but it's nice).** We do not177require that every intermediate commit successfully builds – we only178expect to be able to bisect at a PR level.179However, if you *can* make individual commits build, that is always helpful.180181## Naming conventions182183Apart from normal Rust style/naming conventions, there are also some specific to the compiler.184185- `cx` tends to be short for "context" and is often used as a suffix.186  For example, `tcx` is a common name for the [Typing Context][tcx].187188- [`'tcx`][tcx] is used as the lifetime name for the Typing Context.189190- Because `crate` is a keyword, if you need a variable to represent something191  crate-related, often the spelling is changed to `krate`.192193[tcx]: ./ty.md194195[crates]: ./crates-io.md