代碼風(fēng)格

空白

• 每行不能超出99個字符。
• 縮進只用空格，不用TAB。
• 行和文件末尾不要有空白。

空格

• 二元運算符左右加空格，包括屬性里的等號：

#[deprecated = "Use `bar` instead."]
fn foo(a: usize, b: usize) -> usize {
    a + b
}

• 在分號和逗號后面加空格：

fn foo(a: Bar);

MyStruct { foo: 3, bar: 4 }

foo(bar, baz);

• 在單行語句塊或struct表達式的開始大括號之后和結(jié)束大括號之前加空格：

spawn(proc() { do_something(); })

Point { x: 0.1, y: 0.3 }

折行

• 對于多行的函數(shù)簽名，每個新行和第一個參數(shù)對齊。允許每行多個參數(shù)：

fn frobnicate(a: Bar, b: Bar,
              c: Bar, d: Bar)
              -> Bar {
    ...
}

fn foo<T: This,
       U: That>(
       a: Bar,
       b: Bar)
       -> Baz {
    ...
}

• 多行函數(shù)調(diào)用一般遵循和簽名統(tǒng)一的規(guī)則。然而，如果最后的參數(shù)開始了一個語句塊，塊的內(nèi)容可以開始一個新行，縮進一層：

fn foo_bar(a: Bar, b: Bar,
           c: |Bar|) -> Bar {
    ...
}

// 可以在同一行：
foo_bar(x, y, |z| { z.transpose(y) });

// 也可以在新一行縮進函數(shù)體：
foo_bar(x, y, |z| {
    z.quux();
    z.rotate(x)
})

對齊

常見代碼不必在行中用多余的空格來對齊。

// 好
struct Foo {
    short: f64,
    really_long: f64,
}

// 壞
struct Bar {
    short:       f64,
    really_long: f64,
}

// 好
let a = 0;
let radius = 7;

// 壞
let b        = 0;
let diameter = 7;

避免塊注釋

使用行注釋：

// 等待主線程返回，并設(shè)置過程錯誤碼
// 明顯地。

而不是：

/*
 * 等待主線程返回，并設(shè)置過程錯誤碼
 * 明顯地。
 */

文檔注釋

文檔注釋前面加三個斜線(///)而且提示你希望將注釋包含在 Rustdoc 的輸出里。 它們支持 Markdown 語言 而且是注釋你的公開API的主要方式。

支持的 markdown 功能包括列在 GitHub Flavored Markdown 文檔中的所有擴展，加上上角標。

總結(jié)行

任何文檔注釋中的第一行應(yīng)該是一行總結(jié)代碼的單行短句。該行用于在 Rustdoc 輸出中的一個簡短的總結(jié)性描述，所以，讓它短比較好。

句子結(jié)構(gòu)

所有的文檔注釋，包括總結(jié)行，一個以大寫字母開始，以句號、問號，或者感嘆號結(jié)束。最好使用完整的句子而不是片段。

總結(jié)行應(yīng)該以 第三人稱單數(shù)陳述句形式 來寫。 基本上，這意味著用 "Returns" 而不是 "Return"。

例如：

/// 根據(jù)編譯器提供的參數(shù)，設(shè)置一個缺省的運行時配置。
///
/// 這個函數(shù)將阻塞直到整個 M:N 調(diào)度器池退出了。
/// 這個函數(shù)也要求一個本地的線程可用。
///
/// # 參數(shù)
///
/// * `argc` 和 `argv` - 參數(shù)向量。在 Unix 系統(tǒng)上，該信息被`os::args`使用。
///
/// * `main` - 運行在 M:N 調(diào)度器池內(nèi)的初始過程。
///            一旦這個過程退出，調(diào)度池將開始關(guān)閉。
///            整個池（和這個函數(shù)）將只有在所有子線程完成執(zhí)行后。
///
/// # 返回值
///
/// 返回值被用作進程返回碼。成功是 0，101 是錯誤。

避免文檔內(nèi)注釋

內(nèi)嵌文檔注釋 只用于 注釋 crates 和文件級的模塊：

//! 核心庫。
//!
//! 核心庫是...

解釋上下文

Rust 沒有特定的構(gòu)造器，只有返回新實例的函數(shù)。 這些在自動生成的類型文檔中是不可見的，因此你應(yīng)該專門鏈接到它們：

/// An iterator that yields `None` forever after the underlying iterator
/// yields `None` once.
///
/// These can be created through
/// [`iter.fuse()`](trait.Iterator.html#method.fuse).
pub struct Fuse<I> {
    // ...
}

開始的大括號總是出現(xiàn)的同一行。

fn foo() {
    ...
}

fn frobnicate(a: Bar, b: Bar,
              c: Bar, d: Bar)
              -> Bar {
    ...
}

trait Bar {
    fn baz(&self);
}

impl Bar for Baz {
    fn baz(&self) {
        ...
    }
}

frob(|x| {
    x.transpose()
})

match 分支有大括號，除非是單行表達式。

match foo {
    bar => baz,
    quux => {
        do_something();
        do_something_else()
    }
}

return 語句有分號。

fn foo() {
    do_something();

    if condition() {
        return;
    }

    do_something_else();
}

行尾的逗號

Foo { bar: 0, baz: 1 }

Foo {
    bar: 0,
    baz: 1,
}

match a_thing {
    None => 0,
    Some(x) => 1,
}

一般命名約定

通常，Rust 傾向于為“類型級”結(jié)構(gòu)(類型和 traits)使用 CamelCase 而為“值級”結(jié)構(gòu)使用 snake_case 。更確切的約定：

在 `CamelCase`中, 首字母縮略詞被當(dāng)成一個單詞：用 `Uuid` 而不是 `UUID`。在 `snake_case` 中，首字母縮略詞全部是小寫： `is_xid_start`。 在 `snake_case` 或 `SCREAMING_SNAKE_CASE` 中，“單詞”永遠不應(yīng)該只包含一個字母， 除非是最后一個“單詞”。所以，我們有`btree_map` 而不是 `b_tree_map`，`PI_2` 而不是 `PI2`。 ### 引用函數(shù)/方法名中的類型 函數(shù)名經(jīng)常涉及類型名，最常見的約定例子像 `as_slice`。如果類型有一個純粹的文本名字（忽略參數(shù)）， 在類型約定和函數(shù)約定之間轉(zhuǎn)換是直截了當(dāng)?shù)模? 類型名 | 方法中的文本 --------- | --------------- `String` | `string` `Vec` | `vec` `YourType`| `your_type` 涉及記號的類型遵循以下約定。這些規(guī)則有重疊；應(yīng)用最適用的規(guī)則： 類型名 | 方法中的文本 --------- | --------------- `&str` | `str` `&[T]` | `slice` `&mut [T]`| `mut_slice` `&[u8]` | `bytes` `&T` | `ref` `&mut T` | `mut` `*const T`| `ptr` `*mut T` | `mut_ptr` ### 避免冗余的前綴 一個模塊中的條目的名字不應(yīng)拿模塊的名字做前綴： 傾向于 ``` rust mod foo { pub struct Error { ... } } ``` 而不是 ``` rust mod foo { pub struct FooError { ... } } ``` 這個約定避免了口吃（像 `io::IoError`）。庫客戶端可以在導(dǎo)入時重命名以避免沖突。 ### Getter/setter 方法 一些數(shù)據(jù)類型不希望提供對它們的域的直接訪問，但是提供了 "getter" 和 "setter" 方法用于操縱域狀態(tài) （經(jīng)常提供檢查或其他功能）。 域 `foo: T` 的約定是： * 方法 `foo(&self) -> &T` 用于獲得該域的當(dāng)前值。 * 方法 `set_foo(&self, val: T)` 用于設(shè)置域。（這里的 `val` 參數(shù)可能取 `&T` 或其他類型，取決于上下文。） 請注意，這個約定是關(guān)于通常數(shù)據(jù)類型的 getters/setters， *不是* 關(guān)于構(gòu)建者對象的。 ### 斷言 * 簡單的布爾斷言應(yīng)該加上 `is_` 或者其他的簡短問題單詞作為前綴，e.g.， `is_empty`。 * 常見的例外： `lt`， `gt`，和其他已經(jīng)確認的斷言名。 ### 導(dǎo)入 一個 crate/模塊的導(dǎo)入應(yīng)該按順序包括下面各個部分，之間以空行分隔： * `extern crate` 指令 * 外部 `use` 導(dǎo)入 * 本地 `use` 導(dǎo)入 * `pub use` 導(dǎo)入 例如： ```rust // Crates. extern crate getopts; extern crate mylib; // 標準庫導(dǎo)入。 use getopts::{optopt, getopts}; use std::os; // 從一個我們寫的庫導(dǎo)入。 use mylib::webserver; // 當(dāng)我們導(dǎo)入這個模塊時會被重新導(dǎo)出。 pub use self::types::Webdata; ``` ### 避免 `use *`，除非在測試里 Glob 導(dǎo)入有幾個缺點： * 更難知道名字在哪里綁定。 * 它們前向不兼容，因為新的上流導(dǎo)出可能與現(xiàn)存的名字沖突。 在寫 `test` 子模塊時，為方便導(dǎo)入 `super::*` 是合適的。 ### 當(dāng)模塊限定函數(shù)時，傾向于完全導(dǎo)入類型/traits。 例如： ```rust use option::Option; use mem; let i: isize = mem::transmute(Option(0)); ``` ### 在 crate 級重新導(dǎo)出最重要的類型。 Crates `pub use` 最常見的類型為方便，因此，客戶端不必記住或?qū)?crate 的模塊結(jié)構(gòu)以使用這些類型。 ### 類型和操作在一起定義。 類型定義和使用它們的函數(shù)/模塊應(yīng)該在同一模塊中定義，類型出現(xiàn)在函數(shù)/模塊前面。