Sway 注释风格指南//行注释与/* */块注释的选用原则【免费下载链接】sway Empowering everyone to build reliable and efficient smart contracts.项目地址: https://gitcode.com/GitHub_Trending/sw/swaySway 智能合约语言在 注释 一章中明确定义了两类注释而本仓库的 style-guide/comments.md 则进一步给出注释书写的风格建议绝大多数场景优先使用//行注释但在代码行中段插入说明性文字时改用/* */块注释。读完本文你将掌握 Sway 注释的两种语法形式、它们的适用边界以及文档注释///与工具链的关系并能依据仓库源码理解注释在解析器中的处理方式。一、Sway 注释的两大类别在深入风格建议之前需要先明确 Sway 中注释的整体分类。根据 language/comments/index.mdSway 注释分为两种类别用途常规注释Regular Comments向源码阅读者传达信息不影响程序运行文档注释Documentation Comments对外部使用场景记录功能说明通常由工具用于自动生成文档其中常规注释又细分为两种语法形式// 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_commentDocStyle::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 注释的选用可以收敛为三条简单规则能写独立行或行尾就写//这是风格指南明确鼓励的第一形式可多行堆叠、可附于代码行末是日常注释的主力注释必须嵌入代码中段时改用/* */块注释是行内注释的唯一可行解典型场景即函数声明中在参数之间穿插说明见 函数声明面向外部读者的 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Sway 注释风格指南：`//` 行注释与 `/* */` 块注释的选用原则
Sway 注释风格指南//行注释与/* */块注释的选用原则【免费下载链接】sway Empowering everyone to build reliable and efficient smart contracts.项目地址: https://gitcode.com/GitHub_Trending/sw/swaySway 智能合约语言在 注释 一章中明确定义了两类注释而本仓库的 style-guide/comments.md 则进一步给出注释书写的风格建议绝大多数场景优先使用//行注释但在代码行中段插入说明性文字时改用/* */块注释。读完本文你将掌握 Sway 注释的两种语法形式、它们的适用边界以及文档注释///与工具链的关系并能依据仓库源码理解注释在解析器中的处理方式。一、Sway 注释的两大类别在深入风格建议之前需要先明确 Sway 中注释的整体分类。根据 language/comments/index.mdSway 注释分为两种类别用途常规注释Regular Comments向源码阅读者传达信息不影响程序运行文档注释Documentation Comments对外部使用场景记录功能说明通常由工具用于自动生成文档其中常规注释又细分为两种语法形式// 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_commentDocStyle::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 注释的选用可以收敛为三条简单规则能写独立行或行尾就写//这是风格指南明确鼓励的第一形式可多行堆叠、可附于代码行末是日常注释的主力注释必须嵌入代码中段时改用/* */块注释是行内注释的唯一可行解典型场景即函数声明中在参数之间穿插说明见 函数声明面向外部读者的 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考