Day 16. Solidity Basic Syntax – Style Guide –

The Style Guide in Solidity programming refers to guidelines that dictate the order and manner of coding, focusing on aspects such as how to write and organize code. Adhering to a style guide in coding is crucial for several reasons, including improving readability, facilitating maintenance, unifying code across teams, and preventing errors. Consistently following a coding style guide is essential for the long-term success of a project.

Importance of the Style Guide

Adhering to a style guide in coding holds significant importance for the following reasons:

1. Improved Readability: Coding according to a style guide enhances the readability of the code. Other developers and even your future self can understand the code more quickly and accurately. Consistent naming conventions, appropriate indentation, and the use of comments are crucial for clearly conveying the intent and functionality of the code.
2. Easier Maintenance: Coding that follows a style guide makes code maintenance easier. Code with a consistent style and structure reduces mistakes and hurdles when making changes or corrections, thereby lowering the risk of bugs. This makes it easier for other developers to understand and modify the code quickly, enhancing team productivity.
3. Code Consistency Across Teams: A style guide is an essential tool for ensuring consistency in the codebase across a development team or an entire project. When all team members code according to the same style guide, it unifies the codebase and increases predictability. This enhances the interoperability and shareability of the code, making its management and collaboration easier.
4. Error Prevention: A style guide helps prevent errors by maintaining a consistent coding style. A consistent style makes it easier to spot potential errors early on.

Style Guide

Order of Writing Contract Elements

Write in the following order:

1. pragma statements
2. import statements
3. Interface
4. Library
5. Contract

Interfaces are created using the interface keyword. An interface only holds function prototypes (signatures) and does not include implementation details (meaning it’s not implemented but declares what functions and events it has). Additionally, a Library is a collection of reusable code that provides a set of functions and data structures and is created using the library keyword.

The following example illustrates a file that describes both a Library and a Contract. It defines a library named SafeMath, which is used in the Funding contract. At the beginning, there’s a declaration to apply SafeMath to the uint256 data type, allowing the use of functions defined in SafeMath for uint256 variables within Funding. In line 27, the add function from SafeMath is used.

// SPDX-License-Identifier: MIT
pragma solidity 0.8.13;

import "@openzeppelin/contracts/token/ERC20/ERC20.sol";

library SafeMath {
    ...
    function add(uint256 a, uint256 b) internal pure returns (uint256) {
        uint256 c = a + b;
        assert(c >= a);
        return c;
    }
    ...
}


contract Funding {
    // 型宣言
    using SafeMath for uint256;
    ...
    // 状態変数
    mapping(address => uint256) private s_addressToAmount;
    ...
    // 関数
    function fund() public payable {
      s_funders.push(msg.sender);
      s_addressToAmount[msg.sender].add(msg.value); // add function of SafeMath
      emit Funded(msg.sender, msg.value);
    }
  ...

}

Order of Elements within a Contract

• Type Declarations: Specific types defined apart from basic types, such as enum, struct, library, etc.
• State Variables: Variables used within the contract.
• Events
• Modifiers
• Functions

The order of elements within each contract (or interface, library) is as described above. Please refer to the following example for a practical understanding.

// SPDX-License-Identifier: MIT
pragma solidity 0.8.13;

contract Funding {
  // 型宣言
  using SafeMath for uint256;
  
  // 状態変数
  address[] private s_funders;
  mapping(address => uint256) private s_addressToAmount;
  address public i_owner = 0x5B38Da6a701c568545dCfcB03FcB875f56beddC4;
  
  // イベント
  event Funded(address indexed funder, uint256 indexed fundedAmount);
  
  // modifier
  modifier onlyOwner() {
    require(msg.sender == i_owner, "Only contract owner can call this function");
    _;
  }
  
  // 関数
  function fund() public payable {
    s_funders.push(msg.sender);
    s_addressToAmount[msg.sender].add(msg.value);
    emit Funded(msg.sender, msg.value);
  }
  ...
}

Order of Function Declaration

• constructor
• receive
• fallback
• public
• internal
• private
• view/pure

It is recommended to begin with the constructor (initialization process) and follow the order above. Actual definitions of functions using the ‘function’ keyword start from ‘public’ onwards, with the first three being special types of functions. The ‘receive’ function is automatically called when ETH is directly sent to the contract, while the ‘fallback’ function is used to define code that executes when a function not defined in the contract is called.

natspec

Natspec is a documentation tool integrated into Solidity, designed for writing explanations and documentation for contracts and functions. The name “Natspec” stands for Natural Language Specification. Using Natspec allows for clear documentation about contracts and functions, including the purpose of a contract, the functionality of functions, the meaning of arguments, and the format of return values.

Natspec comments are written as Solidity comments, utilizing a specific structure and tags to organize documentation. The main tags include:

1. @title: Specifies the title or name of the contract, facilitating contract identification and document organization.
2. @author: Indicates the creator of the contract or copyright information, making it clear who holds the copyrights.
3. @notice: Provides information about the usage, precautions, and important details of a contract or function. It’s used to communicate crucial information to users.
4. @dev: A tag for providing information intended for developers, such as internal logic, detailed implementation, and how the contract functions internally.
5. @param: Offers explanations about a function’s arguments, including their names, types, and meanings.
6. @return: Gives details about a function’s return values, describing the type and significance of the returned data.

/**
 * @title A contract for crowdfunding
 * @author simochan
 * @notice This contract is to demo a sample funding contract
 * @dev This implements price feeds as our library
 */
contract Funding {
    // Type Declarations
    using PriceConverter for uint256;
    ...
}