Rust 注释

注释（comment）是你在代码里写给人看的说明文字。Rust 编译时会完全忽略它们，所以注释永远不会影响程序的运行。好的注释解释的是代码为什么这样做，而不只是它做了什么。

行注释

最常见的注释以 // 开头。从 // 开始到这一行结尾的内容都会被忽略：

fn main() {
    // 这是一条注释，Rust 会完全跳过它
    println!("你好！"); // 注释也可以放在行尾
}

输出：

你好！

▶ 动手试一试

多行注释

想写一段比较长的说明，可以在每一行开头都写上 //：

fn main() {
    // 这个程序向用户打招呼。
    // 它只打印一行文字。
    // 作为第一个示例编写。
    println!("你好！");
}

输出：

你好！

▶ 动手试一试

Rust 也支持写在 /* 和 */ 之间的块注释，它可以跨越好几行：

fn main() {
    /*
      这是一条块注释。
      它可以跨越多行，
      不用每行都写 //。
    */
    println!("你好！");
}

输出：

你好！

▶ 动手试一试

实际写代码时，大多数 Rust 代码即使是多行注释也用 //。这是社区的惯例，而且和编辑器的快捷键配合得很好。

把代码注释掉

测试某些东西时，用注释临时禁用一行代码非常方便：

fn main() {
    println!("这一行会运行");
    // println!("这一行暂时关掉了");
}

输出：

这一行会运行

▶ 动手试一试

写出有用的注释

只是把代码复述一遍的注释毫无用处。代码本身已经说明了发生了什么。好的注释要说明为什么，或者提醒读者那些从代码里看不出来的事：

fn main() {
    let minutes = 135;

    // 计时器只显示整小时。整数除法会丢掉余数，
    // 而这正是我们在这里想要的。
    let hours = minutes / 60;
    let leftover = minutes - hours * 60; // 凑不满一小时的分钟数

    println!("{hours} 小时 {leftover} 分钟");
}

输出：

2 小时 15 分钟

▶ 动手试一试

拿它和 // 把分钟数除以 60 这样的注释比一比。后者说的没错，但谁都看得懂 minutes / 60。真正有用的信息是：为什么在这里做除法没问题。

还有几个值得养成的习惯：

让注释跟上代码的变化：和代码对不上的注释比没有注释更糟，因为大家会相信它。
// TODO: 是标记未完成工作的常见写法，比如 // TODO: 处理负数。很多编辑器会高亮它，还能列出项目里所有的 TODO。
Rust 的块注释可以嵌套：和 C 语言不同，你可以把已经包含 /* */ 注释的代码再包进另一个块注释里，照样能正常工作：

fn main() {
    /* 暂时关掉：
       println!("旧的问候"); /* 向所有人问好 */
    */
    println!("新的问候");
}

输出：

新的问候

▶ 动手试一试

文档注释

Rust 还有一种特殊的注释，以 ///（三个斜杠）开头。这就是文档注释（doc comment），用来描述函数，Rust 可以用 cargo doc 把它们生成一个可以浏览的文档网站。

/// 把两个数相加并返回结果。
fn add(a: i32, b: i32) -> i32 {
    a + b
}

作为新手，现在还用不到文档注释。只要知道 /// 是写文档用的，而 // 用来写普通的说明就行。等你准备好了，文档一页会教你怎么写文档注释、生成文档，甚至把示例变成测试。

练习

1. 关掉一行

下面这个程序会打印三行。把中间那行变成注释，让程序只打印 第 1 行 和 第 3 行。提示：在要关掉的那一行开头加上 //。

fn main() {
    println!("第 1 行");
    println!("第 2 行");
    println!("第 3 行");
}

查看答案

fn main() {
    println!("第 1 行");
    // println!("第 2 行");
    println!("第 3 行");
}

输出：

第 1 行
第 3 行

▶ 动手试一试

2. 一次关掉两行

现在打印 第 1 行 到 第 4 行，但只用一个块注释关掉第 2 行和第 3 行。提示：在第 2 行前面用 /* 开始注释，在第 3 行后面用 */ 结束。

查看答案

fn main() {
    println!("第 1 行");
    /*
    println!("第 2 行");
    println!("第 3 行");
    */
    println!("第 4 行");
}

输出：

第 1 行
第 4 行

▶ 动手试一试

总结

注释是 Rust 会忽略的说明文字，用来解释你的代码。
// 开始一条行注释（最常用的一种）。
/* ... */ 是可以写多行的块注释，而且块注释可以嵌套。
好的注释解释为什么，而不是重复代码已经说明的事。
/// 是文档注释，用来生成文档。

小测验

1. Rust 编译代码时，会怎样处理注释？

2. /// 文档注释是用来做什么的？

得分: 0 / 2

Rust 注释

行注释

多行注释

把代码注释掉

写出有用的注释

文档注释

练习

1. 关掉一行

2. 一次关掉两行

总结

小测验

延伸阅读