Solidity 最佳实践清单

好代码不是天生的，而是无数次教训打磨出来的。这份清单浓缩了 OpenZeppelin、Trail of Bits、ConsenSys 与 Foundry 团队在公开报告中反复强调的实践，按维度拆分为五个部分。每条都给出推荐做法与反例。哪怕你只是用来审视自家项目，或者评估 Binance 上挂牌合约的工程水位，它都能起到检查表的作用。

一、代码风格与可读性

命名遵循 mixedCase 函数名、PascalCase 合约名、SCREAMING_SNAKE 常量，参数用 _underscore 前缀避免遮蔽。每个函数加 natspec 注释（@notice、@param、@return），让前端与文档生成器自动获益。

禁止单文件超过 500 行。超过就拆分库或抽象合约。函数体内层级别不超过三层，否则用 early return 或私有函数扁平化。这些细节看似无关安全，但事故复盘中常发现「代码太长导致 reviewer 漏看一行」的案例。维持可读性是工程质量的底层。

二、安全设计的非协商项

Checks-Effects-Interactions 顺序必须严格遵守；外部调用之前先完成全部状态写入。所有 ERC-20 转账使用 safeTransfer 等包装，处理那些不返回 bool 的「坏 token」。所有 public/external 函数都明确权限——public 默认即公开，需要默认拒绝时显式声明 onlyOwner、onlyRole 或 nonReentrant。