How to write comments in solidity| Comment types

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

It improves the 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 the 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 a 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

Solidity - Comments

How to write a single-line comment in Solidity contracts

Solidity multiline comments

Writing documentation solidity Natspec comments?