NatSpec (Natural Language Specification Format) is Ethereum's standard for inline code documentation in Solidity smart contracts. NatSpec comments describe what functions do, their parameters, and return values in a structured format. For security audits, complete NatSpec documentation is essential—it reveals the gap between intended behavior (comments) and actual implementation (code), helping auditors identify bugs faster.

NatSpec Format

NatSpec uses special comment tags:

1/// @title Token Transfer Contract
2/// @author Zealynx
3/// @notice Handles secure token transfers with fee deduction
4/// @dev Uses SafeERC20 for transfer safety
5contract TokenTransfer {
6    
7    /// @notice Transfers tokens with a fee deduction
8    /// @dev Fee is calculated before transfer to avoid rounding issues
9    /// @param recipient Address receiving the tokens
10    /// @param amount Total amount before fee deduction
11    /// @return netAmount Amount actually transferred after fees
12    function transfer(address recipient, uint256 amount) 
13        external 
14        returns (uint256 netAmount) 
15    {
16        // Implementation
17    }
18}

NatSpec Tags

Why NatSpec Matters for Audits

Intent vs Implementation: NatSpec reveals bugs by highlighting mismatches:

1/// @notice Deducts 1% fee from transfers
2function transfer(uint256 amount) external {
3    uint256 fee = amount / 1000;  // Bug: This is 0.1%, not 1%
4    ...
5}

Without documentation, auditors must guess intent. With NatSpec, the discrepancy is obvious.

Reduced discovery time: Auditors charging premium rates don't need to reverse-engineer function purposes—documentation tells them instantly.

Scope clarity: NatSpec on critical functions signals which code needs deepest review.

Audit Preparation Standard

The rule: 100% NatSpec coverage on all public and external functions before audit.

What this means:

• Every external/public function has @notice, @param, @return
• Complex internal functions have @dev notes
• Contract-level documentation explains overall purpose

Time savings: Complete NatSpec can reduce audit discovery phase by hours—hours that would otherwise be billed at auditor rates.

NatSpec Enforcement

Solhint rules:

1{
2  "rules": {
3    "func-named-parameters": "warn",
4    "custom-errors": "warn",
5    "natspec-multiline": "error"
6  }
7}

Static analysis: Some tools flag missing documentation.

CI/CD: Require NatSpec in code review before merge.

Machine-Readable Documentation

NatSpec compiles into JSON documentation:

1solc --userdoc --devdoc Contract.sol

This generates:

• userdoc: User-facing documentation (@notice)
• devdoc: Developer documentation (@dev, @param, etc.)

Tooling can use this for:

• Automated documentation sites
• IDE tooltips
• Contract verification displays

NatSpec Best Practices

Be specific: "Transfers tokens" is useless. "Transfers ERC20 tokens from sender to recipient with 1% fee deduction" is useful.

Document assumptions: "Assumes caller has approved sufficient allowance" prevents misuse.

Explain formulas: Complex calculations need mathematical notation in @dev tags.

Note security considerations: "Reverts if amount exceeds balance" documents expected behavior.

Keep updated: Stale documentation is worse than none—it misleads auditors.

Common Mistakes

Missing return descriptions: @return tags often forgotten but essential for understanding output.

Vague notices: "Does the thing" doesn't help anyone.

Inherited functions undocumented: Use @inheritdoc or write specific notes for overrides.

Implementation details in @notice: User-facing docs shouldn't include internal details.

Example: Well-Documented Function

1/// @notice Withdraws staked tokens after the lock period
2/// @dev Calculates rewards using compound interest formula.
3///      Reverts if lock period hasn't elapsed or amount exceeds stake.
4/// @param amount Number of tokens to withdraw (18 decimals)
5/// @return withdrawn Actual tokens transferred (may differ due to fees)
6/// @return rewards Accrued rewards transferred alongside principal
7function withdraw(uint256 amount) 
8    external 
9    returns (uint256 withdrawn, uint256 rewards) 
10{
11    // Implementation
12}

NatSpec documentation is cheap to write but expensive to lack. Complete documentation accelerates audits and catches intent-implementation mismatches that would otherwise become vulnerabilities.