Good code is self-documenting. However, adding documentation to the code is well worth it, especially for smart contracts.

Let’s see what is NatSpec is and how to utilize it for smart contract documentation.

NatSpec is a special documentation format for Solidity smart contracts. While good contracts can be self-documenting, including NatSpec enables developers to easily share and export documentation.

The NatSpec format consists of specially formatted comments within the Solidity code. NatSpec comments start with `///` for single or `/**` ending with `*/` for multi-line comments. You are probably familiar with this syntax if you read contracts on Etherscan.

NatSpec supports different optional tags that indicate what type of information is provided. Functions usually have multiple tags attached to them, like notice, dev, params, and return.

Here is an example contract from the official Solidity documentation.

Here is a cheat sheet from the official Solidity docs that explains the purpose of each tag and where it may be used.

Once you've written tags a few times, they become familiar and you won't need to consult the cheat sheet anymore.

If no tags are used, then the Solidity compiler will interpret `///` or `/**` comments in the same way as if they were tagged with the notice tag. Nice default right there.

If you are using HardHat, then NatSpec documentation can be easily exported and updated on each compile. You'll have to add and configure `hardhat-docgen` plugin that does the magic. Plugin has different options so set it up as you like.

A good rule of thumb is to always add NatSpec for all public interfaces (everything in the ABI). Exported documentation can be easily understood by your frontend & backend teams that have to integrate smart contracts in the app.

Thanks for reading.

Follow me on Twitter for more!