Solidityにおけるコメント(コメントアウト)の書き方について解説します。
構文
Solidityでのコメントの書き方ですが、基本的には他のプログラミング言語と同じです。
ただ、NatSpec(Solidity独自のフォーマット)がありますので、それについても記します。
一行コメント
ダブルスラッシュ(//)の後にコメントを記します。
// これは一行コメントです
// これは一行コメントです
// これは一行コメントです
複数行コメント
スラッシュとアスタリスク(/*〜*/)でコメントを囲います。
/*
これは複数行コメントです
これは複数行コメントです
これは複数行コメントです
*/
NatSpec(Solidity独自のフォーマット)
開発者やユーザーに向けたコメントを記すための、Solidity独自フォーマットが存在します。
「NatSpec(Ethereum Natural Language Specification Format)」というものです。
コメントアウトの仕方が通常と若干異なっていたり、独自タグがあったりします。
コメントアウト
NatSpecにおいて、一行コメントはトリプルスラッシュ(///)、複数行コメントはスラッシュとダブルアスタリスク〜スラッシュとアスタリスク(/**〜*/)で囲みます。
/// @title タイトル
/// @author 作者名
/**
* @notice ユーザーに向けた説明
* @dev 開発者に向けた詳しい説明
*/
独自タグ
NatSpecにおける独自タグを表にまとめました。
タグ | 説明 | 対象 |
---|---|---|
@title | コントラクト/インターフェースのタイトル | コントラクト/ライブラリ/インターフェース(contract/library/interface) |
@author | 作者名 | コントラクト/ライブラリ/インターフェース(contract/library/interface) |
@notice | ユーザーに向けた何をするものなのかの説明 | コントラクト/ライブラリ/インターフェース/関数/パブリックな状態変数/イベント(contract/library/interface/function/public state variable/event) |
@dev | 開発者に向けた何をするものなのかのより詳しい説明 | コントラクト/ライブラリ/インターフェース/関数/状態変数/イベント(contract/library/interface/function/state variable/event) |
@param | パラメーターの説明 | 関数/イベント(function/event) |
@return | 戻り値の説明 | 関数/パブリックな状態変数(function/public state variable) |
@inheritdoc | ベース関数にて不足しているタグすべてのコピー | 関数/パブリックな状態変数(function/public state variable) |
@custom:... | カスタムタグ | どこでも可(everywhere) |
サンプルコード
// SPDX-License-Identifier: GPL-3.0
pragma solidity >=0.7.0 <0.9.0;
/// @title Test Contract
/// @author Sloth
/// @notice Contract for testing
/// @dev Contract for various development tests
/// @custom:test This is a test contract.
contract Test {
/**
* @notice Calculating addition
* @dev Addition of unsigned integer values
* @param {uint} x
* @param {uint} y
* @return {uint} sum total
*/
function add(uint x, uint y) public pure returns(uint) {
return x + y;
}
}
コメントはこまめに書くようにしましょう。あとで自分がコードを改修するときに役立ちますし、他の開発者にとっても処理の内容を理解しやすくなります。