CompetentIT Solidity Coding Standard

# CompetentIT Solidity Coding Standard Last update: 2021-11-09 ## ***Introduction*** Blockchain SoftWare CompetentIT is written in Solidity, a object-oriented programming language for writing smart contracts. In this document we outline the coding standard that CompetentIT is using for editing Solidity files. :::info :bulb: **Bear in mind**: A coding standard is about consistency. Consistency with this coding standard is important. Consistency within a project is more important. Consistency within one module or function is most important. But most importantly: know when to be inconsistent – sometimes the coding standard just doesn’t apply. When in doubt, use your best judgement. Look at other examples and decide what looks best. And don’t hesitate to ask! ::: ## ***Security Rules*** #### **Avoid to use `.call.value()()`.** #### **Use `keccak256()` instead of deprecated `sha3()`.** #### **Use `selfdestruct()` instead of deprecated `suicide()`.** #### **Use `revert` instead of deprecated `throw`.** #### **Avoid to use `tx.origin`.** #### **Explicitly mark visibility of state.** #### **Compiler version should be the latest at the moment.** #### **Avoid multiple calls of `send` method in single transaction.** #### **Fallback function must be simple.** #### **Check result of `send()` call.** > ***Examples of correct code for this rule:*** >> result of `send()` call checked with if statement: >> ```solidity= >> if(x.send(55)) {} >> ``` > ***Examples of incorrect code for this rule:*** >> result of `send()` call ignored: >> ```solidity= >> x.send(55); >> ``` > [color=orange] #### **Explicitly mark visibility in function. Except for the constructor.** > ***Examples of correct code for this rule:*** >> Functions explicitly marked with visibility: >> ```solidity= >>function b() internal{} >>function b() external {} >>function b() private {} >>function b() public {} >>constructor() {} >> ``` > ***Examples of incorrect code for this rule:*** >> Functions without explicitly marked visibility: >> ```solidity= >> function b() {} >> ``` > [color=orange] #### **Possible reentrancy vulnerabilities. Avoid state changes after transfer.** > ***Examples of correct code for this rule:*** >> Invulnerable Contract 1: >> ```solidity= >> pragma solidity 0.8.10; >> >> contract A { >> mapping(address => uint) private shares; >> >> function b() external { >> uint amount = shares[msg.sender]; >> shares[msg.sender] = 0; >> msg.sender.transfer(amount); >> }// >> } >> ``` >> Invulnerable Contract 2: >> ```solidity= >>pragma solidity 0.8.10; >> >>contract A { >> >> mapping(address => uint) private shares; >> >> function b() external { >> uint amount = shares[msg.sender]; >> user.test(amount); >> shares[msg.sender] = 0; >> }// >>} >> >> ``` >> Invulnerable Contract 3: >> ```solidity= >>pragma solidity 0.8.10; >> >>contract A { >> mapping(address => uint) private shares; >> >> function b() public { >> uint256[] shares; >> uint256 amount = shares[msg.sender]; >> msg.sender.transfer(amount); >> shares[msg.sender] = 0; >> } >> } >> ``` > ***Examples of incorrect code for this rule:*** >> Vulnerable Contract 1: >> ```solidity= >>pragma solidity 0.8.10; >> >> >>contract A { >> >> mapping(address => uint) private shares; >> >> function b() external { >> uint amount = shares[msg.sender]; >> bool a = msg.sender.send(amount); >> if (a) { shares[msg.sender] = 0; } >> } >> >>} >> ``` >> Vulnerable Contract 2: >> ```solidity= >>pragma solidity 0.8.10; >> >> >>contract A { >> >> mapping(address => uint) private shares; >> >> function b() external { >> uint amount = shares[msg.sender]; >> msg.sender.transfer(amount); >> shares[msg.sender] = 0; >> } >> >>} >> ``` > [color=orange] ## Best Practise Rules #### **Function has cyclomatic complexity "current" but allowed no more than 7.** #### **Function body contains "some count" lines but allowed no more than 50.** #### **Line length must be no more than 120.** #### **Contract has "some count" states declarations but allowed no more than 15.** #### **Code mustn't contain empty block.** #### **If variable is created, then it must be used.** #### **Integer variable types must be used with visibly indicated sizes.** #### **Names of constants, variables, functions, contracts and other must be unambiguously interpreted (don't use meaningless names like `a`, `b` , `c` and etc.).** #### **When fallback is not payable you will not be able to receive ethers.** > ***Examples of correct code for this rule:*** >> Fallback is payable: >> ```solidity= >>fallback (bytes calldata _input) external payable returns (bytes memory _output) {} >> ``` > ***Examples of incorrect code for this rule:*** >> Fallback is not payable: >> ```solidity= >> fallback (bytes calldata _input) external returns (bytes memory _output){} >> ``` > [color=orange] #### **Require or revert statement must have a reason string and check that each reason string is at most 32 characters long.** > ***Examples of correct code for this rule:*** >> Require with reason string: >> ```solidity= >>pragma solidity 0.8.10; >> >> >> contract A { >> >> function b() public { >> require(!has(role, account), "Roles: account already has role"); >> role.bearer[account] = true; >> role.bearer[account] = true; >> } >> >> } >> ``` > ***Examples of incorrect code for this rule:*** >> Require without reason string: >> ```solidity= >>pragma solidity 0.8.10; >> >> >> contract A { >> >> function b() public { >> require(!has(role, account)); >> role.bearer[account] = true; >> role.bearer[account] = true; >> } >> >> } >> ``` > [color=orange] > #### **Constructors should use the constructor keyword.** > ***Examples of correct code for this rule:*** >> Require with reason string: >> ```solidity= >>pragma solidity 0.8.10; >> >> >> contract A { >> >> constructor() {} >> >> } >> ``` ## Style Guide Rules ![](https://hackmd.io/_uploads/HJayWRBJa.jpg) #### **Constant name must be in capitalized SCREAMING_SNAKE_CASE.** #### **Contract name must be in PascalCase.** #### **Event name must be in PascalCase.** #### **Function name must be in camelCase.** #### **Function param name must be in camelCase** #### **Modifier name must be in camelCase.** #### **Private and internal names must start with a single underscore.** #### **Avoid to use letters 'I', 'l', 'O' as identifiers.** #### **Variable name must be in camelCase.** #### **Interfaces must be prefixed by "I".** #### **Error must be prefixed with the name of the contract in which it reverted.** #### **Import statements must be on top.** #### **Use double quotes for string literals. Values can be 'single' or 'double'.** > ***Examples of correct code for this rule:*** >> Require with reason string: >> ```solidity= >>pragma solidity 0.8.10; >> >> >> contract A { >> string private a = "test"; >> } >> ``` > ***Examples of incorrect code for this rule:*** >> String with single quotes: >> ```solidity= >>pragma solidity 0.8.10; >> >> >> contract A { >> string private a = 'test'; >> } >> ``` > [color=orange] > #### **Function order is incorrect.** > ***Examples of correct code for this rule:*** >> Constructor is placed before other functions: >> ```solidity= >>pragma solidity 0.8.10; >> >> >> contract A { >> >> constructor() public {} >> function () public payable {} >> >> } >> ``` > ***Examples of incorrect code for this rule:*** >> Constructor is placed after other functions: >> ```solidity= >>pragma solidity 0.8.10; >> >> >> contract A { >> >> function () public payable {} >> constructor() public {} >> >> } >> ``` > [color=orange] #### **Check order of elements in file and inside each contract, according to the style guide** > ***Examples of correct code for this rule:*** >> All units are in order: >> ```solidity= >>pragma solidity 0.8.10; >> >>import "./some/library.sol"; >>import "./some/other-library.sol"; >> >> enum MyEnum { >> Foo, >> Bar >> } >> >> struct MyStruct { >> uint x; >> uint y; >> } >> >>interface IBox { >> function getValue() public; >> function setValue(uint) public; >>} >> >>library MyLibrary { >> function add(uint a, uint b, uint c) public returns (uint) { >> return a + b + c; >> } >>} >> >>contract MyContract { >> using MyLibrary for uint; >> >> struct InnerStruct { >> bool flag; >> } >> >> enum InnerEnum { >> A, B, C >> } >> >> address payable owner; >> uint public x; >> uint public y; >> >> event MyEvent(address a); >> >> modifier onlyOwner { >> require( >> msg.sender == owner, >> "Only owner can call this function." >> ); >> _; >> } >> >> constructor () public {} >> >> fallback () external {} >> >> function myExternalFunction() external {} >> function myExternalViewFunction() external view {} >> function myExternalPureFunction() external pure {} >> >> function myPublicFunction() public {} >> function myPublicViewFunction() public view {} >> function myPublicPureFunction() public pure {} >> >> function myInternalFunction() internal {} >> function myInternalViewFunction() internal view {} >> function myInternalPureFunction() internal pure {} >> >> function myPrivateFunction() private {} >> function myPrivateViewFunction() private view {} >> function myPrivatePureFunction() private pure {} >>} >> ``` > ***Examples of incorrect code for this rule:*** >> State variable declaration after function: >> ```solidity= >>pragma solidity 0.8.10; >> >> >> contract MyContract { >> function foo() public {} >> >> uint a; >> } >> ``` >> Library after contract: >> ```solidity= >>pragma solidity 0.8.10; >> >> contract MyContract {} >> >> library MyLibrary {} >> ``` >> Interface after library: >> ```solidity= >>pragma solidity 0.8.10; >> >> >> library MyLibrary {} >> >> interface MyInterface {} >> ``` > [color=orange] #### **Visibility modifier must be first in list of modifiers.** > ***Examples of correct code for this rule:*** >> Visibility modifier placed first: >> ```solidity= >>pragma solidity 0.8.10; >> >> >> contract A { >> function a() public ownable() payable {} >> } >> ``` > ***Examples of incorrect code for this rule:*** >> Visibility modifier not placed first: >> ```solidity= >>pragma solidity 0.8.10; >> >> >> contract A { >> function a() ownable() public payable {} >> } >> ``` > [color=orange] #### **Recommended that Solidity contracts are fully annotated using NatSpec for all public interfaces (everything in the ABI).** NatSpec comments written with a triple slash (///) or a double asterisk block (/** ... */) and they should be used directly above function declarations or statements and contain the next tags: | Tag | | Context | :----------------:|:-------------------------------:|:---------------:| |`@title`|A title that should describe the contract/interface|contract, library, interface| |`@author`|The name of the author|contract, library, interface| |`@notice`|Explain to an end user what this does|contract, library, interface, function, public state variable, event| |`@dev`|Explain to a developer any extra details|contract, library, interface, function, state variable, event| |`@param`|Documents a parameter just like in Doxygen (must be followed by parameter name)|function, event| |`@return`|Documents the return variables of a contract’s function|function, public state variable| |`@inheritdoc`|Copies all missing tags from the base function (must be followed by the contract name)|function, public state variable| |`@custom:...`|Custom tag, semantics is application-defined|everywhere| ***For exemple:*** > Require with reason string: > ```solidity= >pragma solidity 0.8.10; > > >/// @author The Solidity Team >/// @title A simple storage example >contract SimpleStorage { > uint storedData; > > /// Store `x`. > /// @param x the new value to store > /// @dev stores the number in the state variable `storedData` > function set(uint x) public { > storedData = x; > } > > /// Return the stored value. > /// @dev retrieves the value of the state variable `storedData` > /// @return the stored value > function get() public view returns (uint) { > return storedData; > } >} > ``` > [color=orange] > ## Miscellaneous Check that all public or external functions are override. This is useful to make sure that the whole API is extracted in an interface. > ***Examples of correct code for this rule:*** >> All public functions are overrides: >> ```solidity= >>pragma solidity 0.8.10; >> >> >>contract Foo is FooInterface { >> function foo() public override {} >>} >> ``` > ***Examples of incorrect code for this rule:*** >> A public function is not an override: >> ```solidity= >>pragma solidity 0.8.10; >> >> >>contract Foo { >> function foo() public {} >>} >> ``` > [color=orange]