Sway 注释风格指南：`//` 行注释与 `/* */` 块注释的选用原则

Sway 注释风格指南：//行注释与/* */块注释的选用原则

【免费下载链接】sway🌴 Empowering everyone to build reliable and efficient smart contracts.项目地址: https://gitcode.com/GitHub_Trending/sw/sway

Sway 智能合约语言在 注释 一章中明确定义了两类注释，而本仓库的 style-guide/comments.md 则进一步给出注释书写的风格建议：绝大多数场景优先使用//行注释，但在代码行中段插入说明性文字时改用/* */块注释。读完本文，你将掌握 Sway 注释的两种语法形式、它们的适用边界，以及文档注释///与工具链的关系，并能依据仓库源码理解注释在解析器中的处理方式。

一、Sway 注释的两大类别

在深入风格建议之前，需要先明确 Sway 中注释的整体分类。根据 language/comments/index.md，Sway 注释分为两种：

其中常规注释又细分为两种语法形式：

• // comment：行注释，从两个正斜杠之后开始，一直到该行结束。
• /* comment */：块注释，可以出现在代码的任意位置。

二、风格指南的核心建议：//优先，/* */按需

本仓库的 style-guide/comments.md 给出的风格结论非常简洁明确：

第一种形式（// comment）通常被鼓励；但当注释需要被放置在代码的中间时，第二种形式（/* comment */）被鼓励。

也就是说，Sway 的风格约定并非"禁止块注释"，而是为两种形式划定了各自的最佳场景：

• 默认场景：凡是独立成行的注释、行尾注释，一律使用//。它可以逐行重复堆叠以覆盖多行，也可以紧跟在代码行末尾。
• 代码中段场景：当注释必须"嵌入"在一行代码内部（例如分隔同一行内的多个逻辑片段）时，//会把该行剩余部分全部变成注释，无法胜任，此时应使用/* */块注释精确包裹说明文字。

这一原则在函数声明中得到了具体应用。根据原文档的说明，在函数声明中，第二种形式（块注释）被用来指示附加参数——当函数签名跨越多行、需要在参数之间穿插说明时，块注释不会截断后续的代码。

三、实战示例：两种形式的对照

风格指南所引用的完整可运行示例位于 code/language/comments/src/lib.sw，是comments示例库（对应 Forc.toml）的源码。以下分别展示两种写法。

3.1 行注释//：独立成行与行尾注释

// imagine that this line is twice as long // and it needed to be split onto multiple lines let baz = 8; // Eight is a good number

要点：

• 每个//从注释开始处延续到行尾，多行注释通过每行重复//实现；
• 注释既可以独占一行，也可以附在代码语句末尾（行尾注释）；
• 语句let baz = 8;之后的空间正好适合用//补充简短说明。

3.2 块注释/* */：代码中段的说明

/* imagine that this line is twice as long and it needed to be split onto multiple lines */ let baz = 8; /* Eight is a good number */

要点：

• /* */用一对定界符包裹，天然支持内部换行成块，适合对一段代码做整体解释；
• 关键区别在最后一行：/* Eight is a good number */位于语句内部，块注释结束后该行还能继续书写其他代码。这正是//无法做到、而/* */被鼓励的场景。

四、文档注释///：为工具链而生

与风格指南配套的 language/comments/index.md 同时定义了文档注释：以三个正斜杠///开头，置于函数上方或结构体等类型的字段上方，通常被工具用于自动生成文档。

示例库 lib.sw 中给出了完整范式：

/// Data structure containing metadata about product XYZ struct Product { /// Some information about field 1 field1: u64, /// Some information about field 2 field2: bool, } /// Creates a new instance of a Product /// /// # Arguments /// /// - `field1`: description of field1 /// - `field2`: description of field2 /// /// # Returns /// /// A struct containing metadata about a Product fn create_product(field1: u64, field2: bool) -> Product { Product { field1, field2 } }

从中可以提炼出两条实用约定：

• 结构体层面：在struct声明上方用///描述整体用途，在每个字段上方用///逐一说明字段含义；
• 函数层面：在函数上方用///组织出# Arguments（参数说明）与# Returns（返回值说明）这样的分节结构，便于文档工具解析渲染。

五、编译器视角：注释在 Sway 解析器中的处理

风格与文档注释不只是书写习惯，它们还受到编译器与工具链的正式支持，可以从本仓库源码中得到印证。

5.1 文档注释被解析为属性

在 sway-parse/src/attribute.rs 中，DocComment实现了Peek与Parse：解析器通过peek_doc_comment()探测文档注释，并将其转换为AttributeDecl。关键逻辑如下（源码第 33-45 行）：

• DocStyle::Outer对应外部文档注释///，转换为new_outer_doc_comment；
• DocStyle::Inner对应内部文档注释//!，转换为new_inner_doc_comment。

也就是说，///在语法层面并不是"被丢弃的普通注释"，而是被编译器正式识别为文档属性，从而可以被 forc-doc 等工具消费。相应地，sway-ast/src/attribute.rs 中定义了new_outer_doc_comment、new_inner_doc_comment及is_doc_comment等构造与判定方法，构成文档注释从词法到 AST 的完整链路。

5.2 注释的落位有明确约束

同样在 sway-parse/src/attribute.rs 的测试与错误处理中可以看到：内部文档注释（//!）必须位于文件顶部（否则抛出ExpectedInnerDocCommentAtTheTopOfFile错误），而普通注释则被忽略、不影响解析。这提醒我们：文档注释的书写位置是有语法约束的，而常规注释（//与/* */）则是自由散落的说明性文本，由解析器直接跳过。

六、风格实践小结

结合原文档与示例代码，Sway 注释的选用可以收敛为三条简单规则：

1. 能写独立行或行尾，就写//：这是风格指南明确"鼓励"的第一形式，可多行堆叠、可附于代码行末，是日常注释的主力；
2. 注释必须嵌入代码中段时，改用/* */：块注释是"行内注释"的唯一可行解，典型场景即函数声明中在参数之间穿插说明（见 函数声明）；
3. 面向外部读者的 API 说明，使用///文档注释：置于函数与结构体字段上方，配合# Arguments、# Returns分节，交由 forc-doc 等工具生成文档。

这三条规则与仓库中 style-guide 下的其他规范（如 命名约定、类型标注）共同构成完整的 Sway 代码风格体系，可在编写智能合约时保持注释的一致性与可读性。

【免费下载链接】sway🌴 Empowering everyone to build reliable and efficient smart contracts.项目地址: https://gitcode.com/GitHub_Trending/sw/sway