The Silence of the Comments: Patterns and Pitfalls in Smart Contract Code Documentation

Abstract

In Ethereum's immutable environment, high-quality documentation is essential for users and auditors to fully understand smart contract behavior and build trust. However, an empirical, manually conducted, and comprehensive investigation that analyzes and identifies undocumented implementation details, implicit assumptions, and comment-code inconsistencies in operational smart contracts is still missing. To address this gap, this paper examines the commenting practices occurring in the source code of smart contracts through a systematic manual review of 100 up-to-date Solidity smart contract projects mined from Etherscan, divided into high-usage and low-usage groups based on the number of transactions they received. By combining quantitative analysis, validated with Fisher's exact test, and a multidimensional qualitative checklist, we identify a systemic deficiency in documentation, especially concerning smart contract-specific facets, such as critical security patterns and gas optimization strategies. Our findings show that documentation quality is generally insufficient regardless of a contract's popularity. Smart contract developers tend to prioritize functionality over verifiability, highlighting an urgent need for domain-specific documentation standards and best practices that better support the entire development lifecycle of blockchain applications.