Solidity 风格指南全解:官方编码规范、布局顺序与命名约定实战手册
Solidity 风格指南全解:官方编码规范、布局顺序与命名约定实战手册
本文基于 Solidity 官方仓库的 docs/style-guide.rst 编写,系统讲解 Solidity 源码的代码布局、控制结构写法、合约元素排列顺序与命名约定。指南核心目标是一致性而非"唯一正确写法"——它借鉴 Python PEP 8 的思想,帮助团队在多人协作、审计与开源场景下写出结构统一、可读性高、易于评审的智能合约代码。读完本文,你将掌握官方推荐的缩进、换行、空白、函数排序、命名风格与 NatSpec 注释规范,并能直接应用到自己的合约项目中。
引言:风格指南的定位与优先级
Solidity 官方风格指南的定位非常明确:它不是"最好的写法",而是"一致的写法"。官方文档原文引用 PEP 8 的经典表述——"愚蠢的一致性是小脑袋的妖怪(A foolish consistency is the hobgoblin of little minds)",并给出三层优先级:
- 与官方风格指南保持一致很重要;
- 与项目内部保持一致更重要;
- 与单个模块或函数内部保持一致最为重要。
因此,当项目自有风格与官方指南冲突时,项目特定风格指南优先;当遇到指南未覆盖的场景时,依赖作者的判断力、参考同类优秀示例,并勇于提问。这份指南是"演进中的文档",会随社区沉淀出更有用的约定而持续变化。从源码结构看,该指南的结构与许多推荐均源自 Python 的 PEP 8,例如空行分隔、函数分组、命名风格体系等概念。
值得一提的是,Solidity 编译器自身的 C++ 代码风格(见 CODING_STYLE.md)也遵循类似精神——其"黄金法则"同样是"修改代码时跟随既有代码的风格",并配套 scripts/check_style.sh 在 CI 中自动检查尾随空白、关键字后缺空格等格式问题。这说明风格检查在 Solidity 生态中是被认真对待的工程实践。
代码布局(Code Layout)
缩进与空格
- 每个缩进级别使用 4 个空格。
- 空格是首选的缩进方式,严禁混用 Tab 与空格。
对比:Solidity 编译器自身的 C++ 代码使用 Tab 缩进(见 CODING_STYLE.md),而 Solidity 语言层面的官方指南明确要求 4 空格,两者不要混淆。
空行(Blank Lines)
顶层声明之间用两个空行分隔。SPDX 许可注释与 pragma 之后,每个 contract 之间空两行:
// SPDX-License-Identifier: GPL-3.0
pragma solidity >=0.4.0 <0.9.0;
contract A {
// ...
}
contract B {
// ...
}
contract C {
// ...
}
错误示范(contract 之间仅空一行甚至不空行):
// SPDX-License-Identifier: GPL-3.0
pragma solidity >=0.4.0 <0.9.0;
contract A {
// ...
}
contract B {
// ...
}
contract C {
// ...
}
合约内部:函数声明之间用一个空行分隔。对于抽象合约中成组的相关单行 stub 函数,可以省略空行:
// SPDX-License-Identifier: GPL-3.0
pragma solidity >=0.6.0 <0.9.0;
abstract contract A {
function spam() public virtual pure;
function ham() public virtual pure;
}
contract B is A {
function spam() public pure override {
// ...
}
function ham() public pure override {
// ...
}
}
注意错误示例中 function spam() virtual pure public; 还违反了后文"修饰符顺序"规范(visibility 应在前)。
最大行长(Maximum Line Length)
建议最大行长为 120 字符。需要换行时遵循四条规则:
- 第一个参数不要紧贴左括号;
- 只使用一个缩进级别;
- 每个参数独占一行;
- 终止符
);单独放在最后一行。
函数调用正确示例:
thisFunctionCallIsReallyLong(
longArgument1,
longArgument2,
longArgument3
);
以下均为错误示范(对齐括号、双缩进、同行多参数、括号后紧跟参数、右括号不独立成行等):
thisFunctionCallIsReallyLong(longArgument1,
longArgument2,
longArgument3
);
thisFunctionCallIsReallyLong(
longArgument1, longArgument2,
longArgument3
);
thisFunctionCallIsReallyLong(
longArgument1,
longArgument2,
longArgument3);
赋值语句同样遵循该规则——长表达式左侧保持原样,右侧函数调用按规则换行:
thisIsALongNestedMapping[being][set][toSomeValue] = someFunction(
argument1,
argument2,
argument3,
argument4
);
事件定义与事件触发:
event LongAndLotsOfArgs(
address sender,
address recipient,
uint256 publicKey,
uint256 amount,
bytes32[] options
);
emit LongAndLotsOfArgs(
sender,
recipient,
publicKey,
amount,
options
);
源文件编码
优先使用 UTF-8 或 ASCII 编码。这一点与 Solidity 编译器对源码的解析能力直接相关,非 ASCII 字符应避免出现在标识符中。
Import 语句位置
import 语句必须始终放在文件顶部(SPDX 注释与 pragma 之后、合约定义之前):
// SPDX-License-Identifier: GPL-3.0
pragma solidity >=0.4.0 <0.9.0;
import "./Owned.sol";
contract A {
// ...
}
contract B is Owned {
// ...
}
将 import 混在合约定义之间(如错误示例所示)是官方明确反对的写法。
函数顺序(Order of Functions)
函数排序帮助读者快速识别"哪些函数可以被调用",并更容易找到构造函数与 fallback 定义。按可见性分组,顺序固定为:
constructorreceive函数(若存在)fallback函数(若存在)externalpublicinternalprivate
在同一可见性分组内,将 view 和 pure 函数放在最后。完整正确示例:
// SPDX-License-Identifier: GPL-3.0
pragma solidity >=0.7.0 <0.9.0;
contract A {
constructor() {
// ...
}
receive() external payable {
// ...
}
fallback() external {
// ...
}
// External functions
// ...
// External functions that are view
// ...
// External functions that are pure
// ...
// Public functions
// ...
// Internal functions
// ...
// Private functions
// ...
}
错误示范中把 fallback 提到最前、constructor 塞在 private 之后,破坏了从"入口/构造"到"内部实现"的阅读顺序。
表达式中的空白(Whitespace in Expressions)
在括号、方括号或花括号内侧不要加多余空格(单行函数声明除外):
spam(ham[1], Coin({name: "ham"}));
spam( ham[ 1 ], Coin( { name: "ham" } ) ); // 错误
例外:单行函数体允许紧凑书写:
function singleLine() public { spam(); }
逗号、分号之前不留空格:
function spam(uint i, Coin coin) public; // 正确
function spam(uint i , Coin coin) public ; // 错误
赋值号与运算符两侧只留一个空格,不要为了对齐而加多个空格:
x = 1;
y = 2;
longVariable = 3;
x = 1; // 错误:为了对齐而加多个空格
y = 2;
longVariable = 3;
receive 与 fallback 函数名与括号之间不留空格:
receive() external payable { // 正确
...
}
fallback() external { // 正确
...
}
receive () external payable { // 错误
...
}
控制结构(Control Structures)
contract、library、函数与 struct 的花括号遵循三条规则:
- 左花括号与声明同一行;
- 右花括号独占一行,缩进与声明起始处对齐;
- 左花括号前留一个空格。
contract Coin {
struct Bank {
address owner;
uint balance;
}
}
contract Coin // 错误
{
struct Bank {
address owner;
uint balance;
}
}
if、else、while、for 同理,且关键字与条件括号之间、条件括号与左花括号之间各留一个空格:
if (...) {
...
}
for (...) {
...
}
if (...)
{ // 错误
...
}
while(...){ // 错误
}
for (...) {
...;} // 错误
单语句体可以省略花括号,前提是语句能放在一行内:
if (x < 10)
x += 1;
如果单语句本身是多行的复杂调用,则必须加花括号(错误示例):
if (x < 10)
someArray.push(Coin({ // 错误:多行语句省略了花括号
name: 'spam',
value: 42
}));
else/else if 与 if 的右花括号同行(这是对通用块状结构规则的唯一例外):
if (x < 3) {
x += 1;
} else if (x > 7) {
x -= 1;
} else {
x = 5;
}
if (x < 3)
x += 1;
else
x -= 1;
if (x < 3) { // 错误:else 独占一行
x += 1;
}
else {
x -= 1;
}
函数声明(Function Declaration)
短函数声明
短函数:左花括号与函数声明同行、前留一个空格,右花括号与函数声明同缩进:
function increment(uint x) public pure returns (uint) {
return x + 1;
}
function increment(uint x) public pure onlyOwner returns (uint) {
return x + 1;
}
以下四种均为错误示范(花括号另起一行、括号后无空格直接接花括号、右花括号缩进错误、右花括号与语句同行):
function increment(uint x) public pure returns (uint)
{
return x + 1;
}
function increment(uint x) public pure returns (uint){
return x + 1;
}
function increment(uint x) public pure returns (uint) {
return x + 1;
}
function increment(uint x) public pure returns (uint) {
return x + 1;}
修饰符顺序(Modifier Order)
函数修饰符固定顺序:
- Visibility(可见性:external/public/internal/private)
- Mutability(可变性:view/pure/payable)
- Virtual
- Override
- Custom modifiers(自定义修饰符)
function balance(uint from) public view override returns (uint) {
return balanceOf[from];
}
function increment(uint x) public pure onlyOwner returns (uint) {
return x + 1;
}
function balance(uint from) public override view returns (uint) { // 错误:override 在 view 前
return balanceOf[from];
}
function increment(uint x) onlyOwner public pure returns (uint) { // 错误:自定义修饰符在可见性前
return x + 1;
}
长函数声明
参数较多时:每个参数独占一行,缩进与函数体一致;右括号与左花括号各自独占一行,缩进与函数声明一致:
function thisFunctionHasLotsOfArguments(
address a,
address b,
address c,
address d,
address e,
address f
)
public
{
doSomething();
}
带修饰符的长函数:每个修饰符各占一行:
function thisFunctionNameIsReallyLong(address x, address y, address z)
public
onlyOwner
priced
returns (address)
{
doSomething();
}
function thisFunctionNameIsReallyLong(
address x,
address y,
address z
)
public
onlyOwner
priced
returns (address)
{
doSomething();
}
多行返回值与 return 语句沿用"最大行长"一节的换行规则:
function thisFunctionNameIsReallyLong(
address a,
address b,
address c
)
public
returns (
address someAddressName,
uint256 LongArgument,
uint256 Argument
)
{
doSomething();
return (
veryLongReturnArg1,
veryLongReturnArg2,
veryLongReturnArg3
);
}
继承构造函数的换行
带基类参数的构造函数:若声明较长或难以阅读,将基类构造函数按修饰符同样的方式换行,每个基类一行:
contract B {
constructor(uint) {
}
}
contract C {
constructor(uint, uint) {
}
}
contract D {
constructor(uint) {
}
}
contract A is B, C, D {
uint x;
constructor(uint param1, uint param2, uint param3, uint param4, uint param5)
B(param1)
C(param2, param3)
D(param4)
{
// do something with param5
x = param5;
}
}
注意:错误示例中 D(param4) { 把基类初始化与函数体花括号挤在同一行,以及 { 后函数体多缩进一级,都是不规范写法。
单语句短函数
单语句的短函数允许整行书写:
function shortFunction() public { doSomething(); }
官方特别说明:这些函数声明规则旨在提升可读性,作者应运用最佳判断,因为指南无法覆盖所有可能的组合形态。
变量声明细节
Mapping 声明
mapping 关键字与类型之间不留空格,嵌套 mapping 同样适用:
mapping(uint => uint) map;
mapping(address => bool) registeredAddresses;
mapping(uint => mapping(bool => Data[])) public data;
mapping(uint => mapping(uint => s)) data;
mapping (uint => uint) map; // 错误
mapping( address => bool ) registeredAddresses; // 错误
mapping(uint => mapping (uint => s)) data; // 错误
关于 mapping 类型的完整语义(key 不存储、value 按槽位计算等),可参考 docs/types/mapping-types.rst。
数组声明
类型与方括号之间不留空格:
uint[] x; // 正确
uint [] x; // 错误
其他推荐写法
字符串引号
字符串统一使用双引号,而非单引号:
str = "foo";
str = "Hamlet says, 'To be or not to be...'";
str = 'bar'; // 错误
注意:字符串内部的单引号是允许的,字符串字面量的界定符本身必须用双引号。
运算符两侧空格
运算符两侧各留一个空格:
x = 3;
x = 100 / 10;
x += 3 + 4;
x |= y && z;
x=3; // 错误
x = 100/10; // 错误
x |= y&&z; // 错误
高优先级运算符可以省略两侧空格以表达结合优先级,但两侧空格数必须一致:
x = 2**3 + 5;
x = 2*y + 3*z;
x = (a+b) * (a-b);
x = 2** 3 + 5; // 错误
x = y+z; // 错误
x +=1; // 错误
合约内部布局顺序(Order of Layout)
文件级顺序
一个 Solidity 源文件中,顶层元素按以下顺序排列:
- Pragma 语句
- Import 语句
- Events
- Errors
- Interfaces
- Libraries
- Contracts
合约/库/接口内部顺序
每个 contract、library 或 interface 内部:
- Type declarations(类型声明,如 struct、enum)
- State variables(状态变量)
- Events
- Errors
- Modifiers
- Functions
官方附注:将类型声明放在其被事件或状态变量使用的位置附近可能更清晰(即允许一定的灵活性)。
正确示范(error 声明在函数之前):
// SPDX-License-Identifier: GPL-3.0
pragma solidity >=0.8.4 <0.9.0;
abstract contract Math {
error DivideByZero();
function divide(int256 numerator, int256 denominator) public virtual returns (uint256);
}
错误示范(error 声明在函数之后):
// SPDX-License-Identifier: GPL-3.0
pragma solidity >=0.8.4 <0.9.0;
abstract contract Math {
function divide(int256 numerator, int256 denominator) public virtual returns (uint256);
error DivideByZero();
}
命名约定(Naming Conventions)
命名约定在广泛采用后具有强大的"元信息"传递能力——不同的命名风格可以传达无法立即从字面看出的信息。官方明确:这些是提升可读性的建议而非硬性规则,且代码库内部的持续一致性永远优先于本指南的任何约定。
命名风格体系
为统一表述,官方定义了以下命名风格术语:
| 风格 | 示例 |
|---|---|
b(单个小写字母) |
b |
B(单个大写字母) |
B |
lowercase |
lowercase |
UPPERCASE |
UPPERCASE |
UPPER_CASE_WITH_UNDERSCORES |
MAX_BLOCKS |
CapitalizedWords(CapWords) |
SimpleToken |
mixedCase(首字母小写的 CapWords) |
getBalance |
缩写词(initialisms)规则:CapWords 风格中缩写词全部大写,如 HTTPServerError 优于 HttpServerError;mixedCase 风格中,若缩写词位于名称开头则首字母小写、其余大写,如 xmlHTTPRequest 优于 XMLHTTPRequest。
应避免的命名
禁止使用 l(小写 L)、O(大写 O)、I(大写 I)作为单字母变量名——它们极易与数字 1 和 0 混淆。
各实体命名规范一览
| 实体 | 风格 | 示例 |
|---|---|---|
| 合约与库(Contract/Library) | CapWords | SimpleToken、SmartBank、CertificateHashRepository、Player、Congress、Owned |
| 结构体(Struct) | CapWords | MyCoin、Position、PositionXY |
| 事件(Event) | CapWords | Deposit、Transfer、Approval、BeforeTransfer、AfterTransfer |
| 函数(Function) | mixedCase | getBalance、transfer、verifyOwner、addMember、changeOwner |
| 函数参数(Function Argument) | mixedCase | initialSupply、account、recipientAddress、senderAddress、newOwner |
| 局部与状态变量(Local/State Variable) | mixedCase | totalSupply、remainingSupply、balancesOf、creatorAddress、isPreSale、tokenExchangeRate |
| 常量(Constant) | UPPER_CASE_WITH_UNDERSCORES | MAX_BLOCKS、TOKEN_NAME、TOKEN_TICKER、CONTRACT_VERSION |
| 修饰符(Modifier) | mixedCase | onlyBy、onlyAfter、onlyDuringThePreSale |
| 枚举(Enum) | CapWords | TokenGroup、Frame、HashStyle、CharacterLocation |
合约与库的文件名匹配
合约/库名称应与文件名一致(如合约 Congress 对应 Congress.sol,库 Owned 对应 Owned.sol)。若一个文件包含多个合约/库,文件名应匹配核心合约——但官方不推荐这种写法,能避免就避免。
正确示例——Owned.sol:
// SPDX-License-Identifier: GPL-3.0
pragma solidity >=0.7.0 <0.9.0;
// Owned.sol
contract Owned {
address public owner;
modifier onlyOwner {
require(msg.sender == owner);
_;
}
constructor() {
owner = msg.sender;
}
function transferOwnership(address newOwner) public onlyOwner {
owner = newOwner;
}
}
Congress.sol 中正确导入并继承:
// SPDX-License-Identifier: GPL-3.0
pragma solidity >=0.4.0 <0.9.0;
import "./Owned.sol";
contract Congress is Owned, TokenRecipient {
//...
}
错误示例——文件名小写 owned.sol、合约名小写 owned、继承时引用 tokenRecipient(大小写不一致),都会造成文件名与合约名不匹配、可读性下降:
// SPDX-License-Identifier: GPL-3.0
pragma solidity ^0.7.0;
// owned.sol
contract owned {
address public owner;
modifier onlyOwner {
require(msg.sender == owner);
_;
}
constructor() {
owner = msg.sender;
}
function transferOwnership(address newOwner) public onlyOwner {
owner = newOwner;
}
}
库函数操作自定义结构体的约定
编写操作自定义 struct 的库函数时,struct 必须是第一个参数,且恒命名为 self。这一约定与 Solidity 内置库函数(如对 address、string 等类型的库操作)的惯例一致,便于阅读者立即识别被操作对象。
避免命名冲突:单尾下划线
当期望名称与已有状态变量、函数、内建函数或其他保留名称冲突时,使用 singleTrailingUnderscore_(单个尾下划线) 约定。
非外部函数与变量的下划线前缀
_singleLeadingUnderscore(单个前导下划线) 建议用于非 external 的函数和状态变量(即 private 或 internal;注意:未指定可见性的状态变量默认为 internal)。
这一约定的深层价值在于面向公众的 API 面:前导下划线让读者立即识别函数意图,更重要的是——当把一个函数从 non-external 改为 external(含 public)并相应改名时,会强制你逐一审查所有调用点。这种"改名即审查"的机制是对意外暴露外部函数的重要人工防线,也是常见的安全漏洞来源。官方特别警告:不要用全局查找替换(find-replace-all)工具完成这类改名。
NatSpec 注释规范
Solidity 合约可以使用 NatSpec(Ethereum Natural Language Specification Format)注释为公共接口提供丰富文档。书写形式:三斜杠 /// 或双星号块 /** ... */,置于函数声明或语句正上方。
以下是对 docs/introduction-to-smart-contracts.rst 中"简单存储合约"(SimpleStorage)添加 NatSpec 后的完整示例:
// SPDX-License-Identifier: GPL-3.0
pragma solidity >=0.4.16 <0.9.0;
/// @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;
}
}
官方推荐:所有公共接口(即 ABI 中的一切)都应使用 NatSpec 完整注释。常用标签包括 @title、@author、@notice、@dev、@param、@return 等——编译器只解析 external/public 函数上的标签,并可将这些注释提取为机器可读的输出;第三方工具还可以通过 @custom:<name> 标签携带自定义注解。完整的标签说明与提取格式见 docs/natspec-format.rst。
实战:将风格指南落地到项目中
风格指南若要真正生效,需要工具与流程配合:
- 人工评审维度:Code Review 时可对照本文清单逐项检查——缩进是否 4 空格、空行是否合规、函数是否按可见性分组、修饰符顺序是否正确、mapping/数组声明有无多余空格、命名是否符合各实体规范、公共接口是否补齐 NatSpec。
- 工具链配合:虽然官方仓库的 scripts/check_style.sh 检查的是编译器 C++ 源码风格(尾随空白、关键字后空格、include 写法、指针星号对齐等),但它证明了一个事实:风格规则可以被自动化执行。对于 Solidity 合约项目,社区同样存在多种 lint 与格式化工具可辅助落地本指南;若所在项目已有自有风格规范,按官方建议以项目规范为准。
- 安全联动:函数顺序(constructor → receive → fallback → external → public → internal → private)与下划线前缀约定,本质都是在降低"意外暴露外部接口"的风险。保持这些习惯,能让合约审计与安全评审更快定位到可被任意账户调用的函数面。
结语
Solidity 官方风格指南(docs/style-guide.rst)是一份强调一致性优先的工程文档:从 4 空格缩进、120 字符行长、空行规则,到函数可见性分组、修饰符顺序、mapping 与数组声明细节,再到 CapWords/mixedCase/UPPER_CASE_WITH_UNDERSCORES 的完整命名体系与 NatSpec 注释要求,每一处约定都以"提升可读性、降低协作成本、减少安全失误"为最终目标。把它作为团队的基线规范,在具体场景中结合项目自身约定灵活运用,就是最贴合官方意图的使用方式。