Improving Comments in Solidity

We can improve comments for functions, such that an easy documentation can be obtained about the contract. We will use the markdown documentation comments to write a short documentation along with source code.

Ref: https://docs.soliditylang.org/en/develop/natspec-format.html

/// @notice Constructor that's used to configure the minimum bet per game and the max amount of bets
/// @param _minimumBet The minimum bet that each user has to make in order to participate in the game
/// @param _maxAmountOfBets The max amount of bets that are required for each game
function Casino(uint _minimumBet, uint _maxAmountOfBets) {
    owner = msg.sender;
if (_minimumBet > 0) minimumBet = _minimumBet;
    if (_maxAmountOfBets > 0 && _maxAmountOfBets <= LIMIT_AMOUNT_BETS)
        maxAmountOfBets = _maxAmountOfBets;
// Set the proof of oraclize in order to make secure random number generations
    oraclize_setProof(proofType_Ledger);
}

1. Function Short Description

We can use @notice to give function a short description to let the reader know what the function does.

/// @notice Constructor that's used to configure the minimum bet per game and the max amount of bets

We can optionally use the @author to specify person who wrote the contract.

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
    }

}

2. Parameters Short Description

We can use @param to give details of what the parameter to this function is needed for.

By doing so the function parameter are linked to the @param definition.

/// @param _minimumBet The minimum bet that each user has to make in order to participate in the game
/// @param _maxAmountOfBets The max amount of bets that are required for each game

3. Rest of the one line comments

Now for rest of the comments we can use the regular // to specify the comments on what the line does.

// Check that the amount paid is bigger or equal the minimum bet
assert(msg.value >= minimumBet);

4. Rest of the multi line comments

Now for rest of the multi line comments where a brief description is required, we can use the below approach.

/*
   * This is a multi-line comment in solidity
   * It is very similar to comments in C Programming
*/

Generate Documentation

Now why we did the above is because we can generate documentation from this enriched source code.

enriched documentation

For example to generate the documentation, there is a tool called solmd which generate lightweight markdown documentation for Solidity contracts.

New to trading? Try crypto trading bots or copy trading