[Solidity] How to write a comment (comment-out)?

This section explains how to write a comment (comment-out) in Solidity.

Syntax

The way to write a comment in Solidity is basically the same as in other programming languages.

However, there is a NatSpec (Solidity's own format), which is also described here.

One-line Comment

A double slash (//) is followed by a comment.

// This is a one-line comment
// This is a one-line comment
// This is a one-line comment

Multi-line Comment

Enclose comments with slashes and asterisks (/* - */).

/*
This is a multi-line comment
This is a multi-line comment
This is a multi-line comment
*/

NatSpec (solidity's own format)

Solidity has its own format for comments to developers and users.

It is called NatSpec (Ethereum Natural Language Specification Format).

The comment-out format is slightly different from the usual format, and has its own tags.

Comment-out

In NatSpec, one-line comments are enclosed with triple slashes (///), and multi-line comments are enclosed with slashes and double asterisks to slashes and asterisks (/** - */).

/// @title title
/// @author author

/**
 * @notice Description for users
 * @dev Detailed description for developers
 */

Tags

The table below lists the tags in NatSpec.

Tag	Description	Context
@title	Contract/Interface title	contract, library, interface
@author	Author name	contract, library, interface
@notice	Description of what it does for users	contract, library, interface, function, public state variable, event
@dev	A more detailed description of what it does for developers	contract, library, interface, function, state variable, event
@param	Parameter description	function, event
@return	Return value description	function, public state variable
@inheritdoc	Copy all missing tags in the base function	function, public state variable
@custom:...	Custom tag	everywhere

Sample Code

// 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;
    }

}