Solidity Tutorial : all about Comments

Table of Content

1) How to write Comments in Solidity ?

2) The Different Types of Comments in Solidity

3) NatSpec Comments: what are they ?

4) Using Doxygen Tags with Napstec comments

5) Documentation Output with Natspec

5.1) The Natspec Documentation

5.2) Getting Started

5.3) Developer Documentation output

5.4) User Documentation Output

6) Natspec Developer doc : example

7) Natspec User doc : some examples

7.1) Using Natspec to display custom messages in UI

7.2) Dynamic Expressions in Natspec Comments

8) Atom Plugin to auto-generate Natspec comments

Writing comments in any programming language can be a way to explain what a function performs (but mostly why). As programmers, Robert C. Martin states that “the proper use of comments is to compensate for our failure to express ourself in code”. Therefore, they make the source code easier for human to understand.

When it comes to Solidity, why are comments so important ? Firstly, it might help developer who will inherit that smart contract to understand it. But comments in Solidity

• help developers
• help a user of a smart contract that will consume your smart contract.

1) How to write Comments in Solidity ?

You can write single line comments an multi-line comments using // and /** ... */

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

A good note in Solidity is the following:

A single-line comment is terminated by any unicode line terminator (LF, VF, FF, CR, NEL, LS or PS) in utf8 encoding. The terminator is still part of the source code after the comment, so if it is…