智能合约中使用 NatSpec 的最佳实践

• 原文链接： https://t.co/FgpN0vAsnb
• 译文出自：登链翻译计划
• 译者：翻译小组 校对：Tiny 熊
• 本文永久链接：learnblockchain.cn/article…

摘要： NatSpec 是个注释规范，帮助开发者为其智能合约创建有效的文档。本文介绍 NatSpec的最佳实践，包括理解 NatSpec 标签、定义范围、提供上下文描述、保持参数顺序一致、记录前提条件和检查，以及使用 Etherscan 等工具。遵循这些最佳实践将有助于为智能合约创建强大和用户友好的文档。

概述

我们将探讨利用 NatSpec 为智能合约创建有效的文档的最佳做法，以便更有效地描述智能合约的功能和约束。

强调正确的代码规范对开发人员是非常重要性的，有几处重要需要关注的地方：

1. 了解NatSpec标签

2. 定义范围

3. 上下文描述

4. 参数顺序的一致性

5. 前提条件和检查

6. 工具

了解 NatSpec 标签

NatSpec 提供了不同的标签来帮助指导你描述的具体内容。全部的标签和用法可以查看文档， 以下是一个NatSpec 示例：

 // SPDX-License-Identifier: GPL-3.0
 pragma solidity >=0.8.2 < 0.9.0;

 /// @title A simulator for trees
 /// @author Larry A. Gardner
 /// @notice You can use this contract for only the most basic simulation
 /// @dev All function calls are currently implemented without side effects
 /// @custom:experimental This is an experimental contract.
 contract Tree {
 }

两个类似标签是@dev和@notice。理解何时使用这些标签对于制作有针对性的文档至关重要。

@dev标签是针对开发者和第三方集成商的，允许对一个功能或合约进行更多的技术描述，用于详细说明复杂的逻辑结构、底层算法和集成接口。

另一方面，@notice是为面向终端用户而设计的。这个标签所包含的信息旨在简化，减少技术术语，是在交易过程中显示给用户的内容，描述代码的作用。

定义范围

当一个函数接受一个范围作为参数的情况下，明确定义边界是包含的还是排除的是至关重要的。这种明确性将指导用户提供适当的值，并防止潜在的交易失败。

你可以用方括号[]表示包含，用圆括号()表示排除。

例如，[startIndex, endIndex)的函数范围意味着 startIndex 包括在该范围内，而 endIndex 被排除在外。

在可能的情况下，Natspec描述应该提供额外的背景。例如，如果一个函数要求输入的精度比例为1e18或以代币的最小单位计算，则应在描述中明确说明。

上下文描述

你可以通过NatSpec添加到上下描述， 类似这样：

参数顺序的一致性

为了提高可读性和理解性，确保 Natspec 注释中的参数顺序与函数参数顺序一致。文档和函数之间的顺序不一致可能会导致开发人员和最终用户的混淆。

下面是一个简化的例子，说明当函数定义中的参数顺序与NatSpec注释中的顺序不一致时：

这可能导致读者在试图理解如何正确使用transfer函数时感到困惑。

正确的做法是将NatSpec中参数的顺序与函数定义中的顺序相匹配：

前提条件和校验

记录前提条件和检查是必不可少的，这样合约才能安全地按照预期的方式行事。此外，提供这些注意事项可以帮助用户理解合约的约束。

工具

为了进一步提高你的文档的可访问性，利用支持NatSpec的平台，如Etherscan。Etherscan提供了一个用户友好的界面来查看合约细节，包括NatSpec注释。

以下是NatSpec在Etherscan上如何显示两种流行协议的例子：

AaveV3：https://etherscan.io/address/0xa700b4eb416be35b2911fd5dee80678ff64ff6c9#readProxyContract

UniV3：https://etherscan.io/address/0xc36442b4a4522e871399cd717abdd847ab11fe88#readProxyContract

在合约代码中加入Natspec注释，可以让任何通过Etherscan与你的合约进行交互的人看到，并显著提高合约的可用性和用户体验。

结论

遵循这些最佳实践将帮助你为智能合约创建强大的、用户友好的文档，并最终使它们对开发者、审计和最终用户都更容易使用。

如果你觉得文章对你有帮助 ，请关注 @HickupH 以及 @SpearbitDAO ，以便在未来获得类似的讲解。

本翻译由 DeCert.me 协助支持， DeCert.me的口号是 码一个未来， 支持每一位开发者构建自己的可信履历。