【CryptZombies】レッスン５チャプター１３：コメント

コメントのシンタックス（構文）

SolidityにおけるコメントはJavaScriptのものと似ています。

// これは1行コメントだ。自分への(または他者へ向けた)注意書きのようなものだ。

ただ//をコメントする箇所に加えれば良い。非常に簡単です。

こんな複数行のコメントもできます:

contract CryptoZombies {
  /* This is a multi-lined comment. I'd like to thank all of you
    who have taken your time to try this programming course.
    I know it's free to all of you, and it will stay free
    forever, but we still put our heart and soul into making
    this as good as it can be.

    Know that this is still the beginning of Blockchain development.
    We've come very far but there are so many ways to make this
    community better. If we made a mistake somewhere, you can
    help us out and open a pull request here:
    https://github.com/loomnetwork/cryptozombie-lessons

    Or if you have some ideas, comments, or just want to say
    hi - drop by our Telegram community at https://t.me/loomnetwork
  */
}

特に、コントラクト中の各関数に期待する働きをコメントして説明するのは良いことです。こうして他の開発者が、コード自体を読まずに、コードの働きの概要をさっと理解することができます。


Solidityのコミュニティでは、 natspec というフォーマットを用いることがスタンダードとなっています。

/// @title A contract for basic math operations
/// @author H4XF13LD MORRIS 💯💯😎💯💯
/// @notice For now, this contract just adds a multiply function
contract Math {
  /// @notice Multiplies 2 numbers together
  /// @param x the first uint.
  /// @param y the second uint.
  /// @return z the product of (x * y)
  /// @dev This function does not currently check for overflows
  function multiply(uint x, uint y) returns (uint z) {
    // This is just a normal comment, and won't get picked up by natspec
    z = x * y;
  }
}

@title と @authorはそのままの意味です。

@notice は ユーザー に、コントラクトや関数が何を行うか説明します。
@devは開発者向けのさらなる詳細の説明です。

@paramと@returnでは、関数の各パラメーターが何であり、どんな値を返すのかを記述します。

すべてのタグはオプショナルなので、各関数にこれらすべてのタグを使用すべきというわけではありません。しかし最低でも@devタグで各関数の働きを説明することはしておきましょう。

テストの実行

今まで気づかなかったかもしれないが、クリプトゾンビの答え合わせの際コメントは無視されている。なのでこのチャプターではnatspecコードの答え合わせができない ;)
だがこれまでお主はSolidityの達人だったから、これもできると仮定しよう！
どちらにせよ挑戦してみるのだ。ZombieOwnershipにnatspecタグを加えてみよう:

①@title — 例：ゾンビ所有権の移転を管理するコントラクト

/// @title ゾンビ所有権の移転を管理するコントラクト

②@author — お主の名前だ!

/// @author nomadomama

③@dev — 例：OpenZeppelinのERC721ドラフト実装に準拠

/// @dev OpenZeppelinのERC721ドラフト実装に準拠

お疲れさまでした！

＜参考＞
CryptoZombies - イーサリアム上でゲームを開発する方法を学習。Powered by Loom Network