SolidityのNatSpecコメントとその用法について

概要

Smart contract開発では、ソースコードの可読性や保守性を高めるために、正しくドキュメンテーションを行うことが非常に重要です（Smart contractに限った話ではないですが）。Solidityでは、このためにNatSpec（Natural Specification）と呼ばれる特殊なコメント機能が提供されています。この記事では、SolidityのNatSpecコメントの各タグについて詳しく説明します。

NatSpecとは

NatSpecは、EthereumのSmart Contractsのためのドキュメンテーションフォーマットです。開発者はこの形式を使用して、Smart Contractsとその関数の振る舞いについて詳細な説明を提供できます。

主なNatSpecタグとその用法

以下に、NatSpecの主なタグとその用法について解説します。

1. @title:

   @titleタグは、コントラクトのタイトルを定義します。一つのコントラクトにつき一つだけ指定可能です。

   /// @title A simple greeter contract
   contract Greeter {
       // ...
   }
   

2. @notice:

   @noticeタグは、ユーザーに表示するための説明を提供します。これは、関数やコントラクト全体に関する説明文を作成するのに使われます。

   /// @notice Calculate the sum of two numbers
   function add(uint a, uint b) public pure returns(uint) {
       return a + b;
   }
   

3. @dev:

   @devタグは、開発者向けの詳細な説明を提供します。コードの内部ロジックや注意事項をここで説明します。（個人的に頻度高め）

   /// @dev Be aware that this function does not check for overflows
   function multiply(uint a, uint b) public pure returns (uint) {
       return a * b;
   }
   

4. @param:

   @paramタグは、関数のパラメータについて説明します。各パラメータは新たな@paramタグで説明されます。

   /// @param a The first number
   /// @param b The second number
   function subtract(uint a, uint b) public pure returns (uint) {
       return a - b;
   }
   

5. @return:

   @returnタグは、関数の戻り値について説明します。

   /// @return The difference of a and b
   function subtract(uint a, uint b) public pure returns (uint) {
       return a - b;
   }
   

6. @inheritdoc:

   @inheritdocタグは、スーパーコントラクトから注釈を継承します。

   /// @inheritdoc SuperContract
   function myFunction() public {
   }
   

以上が主なNatSpecのタグです。これらを適切に使用することで、Solidityのコードはより読みやすく、理解しやすいものになります。

まとめ＆所感

最初はSpring bootっぽいなーって思ったけど全然違いました。