You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Contract-level documentation is user-visible (because people read Etherscan) and NatSpec specifies that it can be shown to users. Every contract should explain what it does cleary.
For contracts that are deployed (i.e. not abstracts and mix-ins) the top-level documentation should be spectacular.
Recommendation: update contract so that when the compiled contract is opened in Etherscan it will look like a million-dollar effort went into it.
NatSpec documentation is provided for most functions, that’s great!
The @notice tag for functions is user-visible documentation. So it should be included for every public function. In the future, wallets and Etherscan will show these notes to end-users when transactions are being signed.
Recommendation: achieve 100% public function-level NatSpec coverage (including public variables which are implicitly functions).
Additional notes: as developers we often think “this function name will be obvious to all users”. But the function isOpen() refers to only a specific state of the CountdownGriefingEscrow contract. It is very reasonable for someone to look at that and think that all non-terminal states would count as true for isOpen()
Contract-level documentation is user-visible (because people read Etherscan) and NatSpec specifies that it can be shown to users. Every contract should explain what it does cleary.
For contracts that are deployed (i.e. not abstracts and mix-ins) the top-level documentation should be spectacular.
Recommendation: update contract so that when the compiled contract is opened in Etherscan it will look like a million-dollar effort went into it.
Here is some artwork to get you started:
And if you want to restrict to ASCII:
References:
Su Squares introduction: https://github.com/su-squares/ethereum-contract/blob/master/contracts/ALLINONE.sol
Function-level documentation is incomplete
NatSpec documentation is provided for most functions, that’s great!
The
@notice
tag for functions is user-visible documentation. So it should be included for every public function. In the future, wallets and Etherscan will show these notes to end-users when transactions are being signed.Recommendation: achieve 100% public function-level NatSpec coverage (including public variables which are implicitly functions).
Additional notes: as developers we often think “this function name will be obvious to all users”. But the function
isOpen()
refers to only a specific state of theCountdownGriefingEscrow
contract. It is very reasonable for someone to look at that and think that all non-terminal states would count as true forisOpen()
References:
erasure-protocol/contracts/escrows/CountdownGriefingEscrow.sol
Line 446 in 4a3d98c
The text was updated successfully, but these errors were encountered: