Solidity-natspec注释

以下内容为僵尸游戏中的教学章节的简介,之前在国内百度是natspec是比较少内容,所需先驱大佬已经完成了许多文档整理工作
如登链的https://learnblockchain.cn/docs/solidity/natspec-format.html


僵尸游戏的 Solidity 代码终于完成啦。 在以后的课程中,我们将学习如何将游戏部署到以太坊,以及如何和 Web3.js 交互。 不过在你离开第五课之前,我们来谈谈如何 给你的代码添加注释. 注释语法 Solidity 里的注释和 JavaScript 相同。在我们的课程中你已经看到了不少单行注释了: // 这是一个单行注释,可以理解为给自己或者别人看的笔记 只要在任何地方添加一个 // 就意味着你在注释。如此简单所以你应该经常这么做。 不过我们也知道你的想法:有时候单行注释是不够的。毕竟你生来话痨。 所以我们有了多行注释: contract CryptoZombies { /* 这是一个多行注释。我想对所有花时间来尝试这个编程课程的人说声谢谢。 它是免费的,并将永远免费。但是我们依然倾注了我们的心血来让它变得更好。 要知道这依然只是区块链开发的开始而已,虽然我们已经走了很远, 仍然有很多种方式来让我们的社区变得更好。 如果我们在哪个地方出了错,欢迎在我们的 github 提交 PR 或者 issue 来帮助我们改进: https://github.com/loomnetwork/cryptozombie-lessons 或者,如果你有任何的想法、建议甚至仅仅想和我们打声招呼,欢迎来我们的电报群: https://t.me/loomnetworkdev */ } 特别是,最好为你合约中每个方法添加注释来解释它的预期行为。这样其他开发者(或者你自己,在6个月以后再回到这个项目中)可以很快地理解你的代码而不需要逐行阅读所有代码。 Solidity 社区所使用的一个标准是使用一种被称作 natspec 的格式,看起来像这样: /// @title 一个简单的基础运算合约 /// @author H4XF13LD MORRIS 💯💯😎💯💯 /// @notice 现在,这个合约只添加一个乘法 contract Math { /// @notice 两个数相乘 /// @param x 第一个 uint /// @param y 第二个 uint /// @return z (x * y) 的结果 /// @dev 现在这个方法不检查溢出 function multiply(uint x, uint y) returns (uint z) { // 这只是个普通的注释,不会被 natspec 解释 z = x * y; } } @title(标题) 和 @author (作者)很直接了. @notice (须知)向 用户 解释这个方法或者合约是做什么的。 @dev (开发者) 是向开发者解释更多的细节。 @param (参数)和 @return (返回) 用来描述这个方法需要传入什么参数以及返回什么值。 注意你并不需要每次都用上所有的标签,它们都是可选的。不过最少,写下一个 @dev 注释来解释每个方法是做什么的。 实战演习 如果你还没注意到:CryptoZombies 的答案检查器在工作的时候将忽略所有的注释。所以这一章我们其实无法检查你的 natspec 注释了。全靠你自己咯。 话说回来,到现在你应该已经是一个 Solidity 小能手了。我们就假定你已经学会这些了。 大胆去做些尝试把,给 ZombieOwnership 加上一些 natspec 标签: @title — 例如:一个管理转移僵尸所有权的合约 @author — 你的名字 @dev — 例如:符合 OpenZeppelin 对 ERC721 标准草案的实现

  

posted @ 2022-09-05 23:34  ZaleSwfit  阅读(88)  评论(0编辑  收藏  举报