Comments are a useful description of line or block code that helps developers to understand the code better.

It improves maintenance of the code to easy for multiple developers.

A solidity programming language supports various comment types.

  • Single line and inline comments
  • Multiline or block line comments
  • Documentation or natspec comments.

Comments text is ignored by the compiler and it does not generate in byte code.

How to write a single line comment in Solidity contracts

Single-line comments are added as a new line or inline to code.

Single-line Comments always start with a double forward slash // symbol followed by text content.

Syntax:

// Single line comment example

Here is a solidity smart contract single line comment example

// SPDX-License-Identifier: UNLICENSED

pragma solidity ^0.8.0;

import "hardhat/console.sol";
// Hello world comments
contract WavePortal {

    constructor() {
        console.log("Hello World Smart Contract Example"); // inline comments
    }

}

Solidity multiline comments

Comments text does span in multiple lines, These are also called block-level comments.

These comments start with /* and are followed by the text content in multiple lines, and end with */. Here is a syntax example

/*
*
* multi-line comment line1
* multi-line comment line2
*/

Here is an example

// SPDX-License-Identifier: UNLICENSED

pragma solidity ^0.8.0;

import "hardhat/console.sol";
/*
* Hello world example code
* Helloworld.sol file
*/
contract WavePortal {

    constructor() {
        console.log("Hello World Smart Contract Example"); // inline comments
    }

}

Writing documentation solidity Natspec comments?

Every program provides documentation for API and an end-user guide for understanding the code.

Solidity provides special comments syntax for writing documentation comments in the code using `Ethereum Natural Specification(Natspec) syntax

It provides rich documentation for contract functions, classes, and interfaces using the Doxygen notation format.

It helps the user to write user and developer documentation.

These can be included with single or multiple line comments

  • Single line comments three double slashes(///)
  • Multiple line comments start with /* and end with */

It contains following tags

tags Description used before
@title Contract class or interface title description Class and interface
@author Author name for contract Contract class or interface,function
@notice Enduser note explains what does it do Contract class or interface, function
@dev developer notes about code what does it do Contract class or interface, function
@param parameters to function function
@return return types of an function function

Here is an example

// SPDX-License-Identifier: UNLICENSED

pragma solidity ^0.8.0;

import "hardhat/console.sol";
/*
* @author John
* @notice Hello World First Smart Contract example
*/
contract WavePortal {

    constructor() {
        console.log("Hello World Smart Contract Example"); // inline comments
    }

}

Once you have the smart contract file, we have to run the following with a solidity compiler.

solc --userdoc --devdoc Helloworld.sol

solc is a solidity compiler generated for compiling contracts.

--userdoc : generates solidity user documentation --devdoc : generates solidity developer documentation

It generates User and developer documentation json file.

user documentation json:

{

  "notice" : "Hello World First Smart Contract example"
}

Developer documentation json doc:

{
  "author":"user",
  "notice" : "Hello World First Smart Contract example"
}

Notes:

  • Solidity contracts are compiled to low-level code i.e machine-readable code
  • Regular comments are not included in machine-readable code
  • Document comments are included in machine-readable code