注释是写在接口上还是实现类上_一起学Rust编程「11」：注释

于 2020-12-03 06:47:31 发布

· 945 阅读

文章标签：

本文介绍了Rust编程中注释的语法和重要性，强调了良好注释应具备的功能，如解释函数、模块、原因、原理和提醒。同时，列举了糟糕注释的类型，提倡根据目标读者来决定是否添加非无脑解释的注释，主张写注释如同写文章，需站在读者角度考虑。

摘要生成于 C知道，由 DeepSeek-R1 满血版支持，前往体验 >

注释的写法，主要有2类：

// 行注释：本行跟在//后面的内容都是注释的部分

/* 块注释。*/

/*
 * 多行块注释
 * 1. ****
 * 2. ****
 * 的
*/

/*
另一种风格的多行注释。
*/

还有一种特殊情况，三个斜线///开头的行注释是Rust的文档注释：

/// 定义一个屏幕上的点
pub struct Pixel {
    /// x轴是从左到右，从0开始
    x: u32,
    /// y轴是从上到下，从0开始
    y: u32,
}

cargo doc命令可以把这样的注释自动提取成文档，输出到target/doc目录下。这对于生成程序接口的参考手册非常方便。

有用的注释：

1. 函数的注释。

高质量的函数应该有一个清晰的接口：这个函数做什么用，怎么传参，怎么使用返回值，怎么处理错误。如果调用函数的人看了函数注释，不需要去理解函数体，就能正确使用，这个注释就是很好的。

2. 模块的注释。