NatSpec
NatSpec (Natural Language Specification) is a system for documenting solidity code in a way that is easy for humans to understand. NatSpec comments are written in Markdown format and can be accessed through the Ethereum NatSpec Standard JSON Interface. To add single-line NatSpec documentation to your Solidity code, use double-slash comments (‘//’) followed by the NatSpec tag and the documentation text. And for adding multiple comments (“/**…..*/”) Here’s an example to refer to while writing comments.
/**
@notice Description of the function
@param Parameter1 Description of parameter1
@param Parameter2 Description of parameter2
@return Description of the return value
*/
Below is the solidity code to demonstrate how to comment using the NatSpec format:
Solidity
// SPDX-License-Identifier: GPL-3.0 pragma solidity >=0.8.6 <0.9.0; /// @title A contract for demonstrate NatSpec format /// @author Jitendra Kumar /// @notice For now, this contract just show how to comment using NatSpec format contract helloGeeks { /// @notice Return an initialized string /// @return A string helloGeeks function renderHelloGeeksFun () public pure returns (string memory) { return 'helloGeeks' ; } } |
Explanation:
- With reference to the attached snippet, we can see the code layout used here and can verify the order of layout (i.e. Pragma statement followed by Contract and finally Function definitions). Check whether the naming convention guidelines are also followed or not and NatSpec declaration of comments is included or so.
- This is a simple Solidity contract that defines a single function called “renderHelloGeeksFun”. The function has no input parameters and returns a string. The “pragma solidity” line at the top of the contract specifies the version of Solidity that the contract is compatible with. In this case, the contract is compatible with any version of Solidity between 0.8.6 and the latest version.
- The “pure” keyword in the function declaration indicates that the function does not modify the contract’s state and does not have any external side effects. This makes the function cheaper to execute because it does not require any resources beyond the computation of its return value.
- The “returns” clause specifies the type and name of the value that the function returns. In this case, the function returns a string called “string” and the data location is “memory” for this string.
- The function body consists of a single return statement that returns the string “helloGeeks”. Overall, this contract defines a simple function that returns a fixed string when it is called. It does not do anything else.
Solidity – Style Guide
Solidity is a computer programming language used to create Ethereum smart contracts. These contracts self-execute. The code and the agreements contained therein are enforced by the blockchain network. Solidity is a high-level language, meaning that it is designed to be human-readable and easy to write. It is based on the JavaScript programming language and has a syntax similar to C++. Solidity is a statically-typed language, meaning that variables have a fixed type that must be declared when they are created. It also supports complex data types such as arrays and structs (collections of related variables).
One of the main benefits of Solidity is that it allows developers to build decentralized applications (DApps) on the Ethereum platform. These DApps can be used for a wide range of applications, including supply chain management, voting systems, and financial applications.
In this style guide, we will cover several elements starting with code layout till NatSpec declaration in code, followed by an example for better understanding.