【Python基础】 13 Rust 与 Python 注释对比笔记

1. 注释语法对比

特性	Rust	Python	说明
单行注释	`// 注释内容`	`# 注释内容`	语法不同，目的相同
多行注释	`/* 注释内容 */`	`''' 注释内容 '''` 或 `""" 注释内容 """`	Rust 使用 C 风格；Python 使用三引号（本质是字符串，惯用作注释）
文档注释（模块/项）	`/// 注释内容`	`"""注释内容"""`	Rust 专用语法；Python 使用文档字符串（Docstring）
文档注释（crate/模块）	`//! 注释内容`	`"""模块注释内容"""`	Rust 用于注释包含它的模块或 crate；Python 模块文档也写在文件顶部用 `"""`
嵌套注释	支持 (`/* /* / /`)	不支持	Rust 允许注释嵌套，便于快速注释掉包含注释的代码块

2. 文档注释与工具链对比 (核心差异)

方面	Rust	Python
官方工具	`rustdoc`	`pydoc` , `Sphinx` (第三方，事实标准)
生成命令	`cargo doc`	`pydoc3 -w module_name` 或 `sphinx-build`
输出格式	静态 HTML（功能丰富，风格统一）	HTML（`pydoc` 简单，`Sphinx` 强大且可定制）
核心特性	Markdown 支持、代码示例测试、搜索	reStructuredText (Sphinx)、类型注解提示 (Python 3)
代码测试	`cargo test` 会自动运行文档中的代码示例！	需使用 `doctest` 模块手动集成或使用 Sphinx 的 `doctest` 扩展
链接系统	非常强大。使用 [``] 语法可轻松链接到其他项	相对较弱。在 Sphinx 中需要使用特定语法创建交叉引用

3. 示例代码对比

单行与多行注释

rust 复制代码

// 这是一个简单的 Rust 单行注释

/*
    这是一个多行注释
    可以跨越多行
*/

let x = 5; // 也可以注释在行尾

python 复制代码

# 这是一个简单的 Python 单行注释

'''
这是一个多行注释（实际上是一个字符串）
Python 解释器会忽略未赋值的字符串。
'''
"""
 triple-double-quotes 也可以。
"""

x = 5  # 也可以注释在行尾

文档注释

rust 复制代码

/// 构造一个新的 `Rectangle` 实例。
///
/// # 示例 (这是一个 Markdown 标题)
///
/// ```rust
/// let rect = Rectangle::new(30, 50);
/// assert_eq!(rect.width, 30);
/// ```
pub struct Rectangle {
    /// 矩形的宽度。
    pub width: u32,
}

python 复制代码

class Rectangle:
    """
    表示一个矩形。

    Attributes:
        width (int): 矩形的宽度。
        height (int): 矩形的高度。
    """

    def __init__(self, width, height):
        """初始化 Rectangle 实例。
        
        Args:
            width (int): 矩形的宽度，必须为正数。
        """
        self.width = width

4. 总结与关键差异

特性	Rust	Python	结论
哲学	文档是第一公民。注释是语言语法的一部分，工具链深度集成。	约定优于配置。文档是强大且普遍遵循的约定，但工具更多样化。	Rust 提供了更"全包"和标准化的体验。
测试集成	无敌强大。`cargo test` 直接测试文档示例，确保文档和代码同步。	需要额外配置（如 `doctest` 模块或 Sphinx 扩展）。	Rust 在保证文档准确性方面做得更彻底。
交叉引用	一流支持。[``SomeStruct]` 语法非常方便。	较弱，严重依赖 Sphinx 等第三方工具和特定语法。	Rust 开发者编写内部链接的体验更好。
标记语言	Markdown	reStructuredText (Sphinx 主流)	取决于开发者更熟悉哪种标记语言。
文化	强烈鼓励文档注释。标准库和所有主流库都有极其完善的文档。	强烈鼓励文档字符串 (Docstring)。PEP 257 定义了约定，几乎所有开源库都遵守。	两者都拥有强大的文档文化。