Solidity 风格指南全解:官方编码规范、布局顺序与命名约定实战手册

原创2026-09-11 23:04:541,849 阅读
文章标签:编译器编程语言区块链Web3形式化验证开发工具

Solidity 风格指南全解:官方编码规范、布局顺序与命名约定实战手册

本文基于 Solidity 官方仓库的 docs/style-guide.rst 编写,系统讲解 Solidity 源码的代码布局、控制结构写法、合约元素排列顺序与命名约定。指南核心目标是一致性而非"唯一正确写法"——它借鉴 Python PEP 8 的思想,帮助团队在多人协作、审计与开源场景下写出结构统一、可读性高、易于评审的智能合约代码。读完本文,你将掌握官方推荐的缩进、换行、空白、函数排序、命名风格与 NatSpec 注释规范,并能直接应用到自己的合约项目中。


引言:风格指南的定位与优先级

Solidity 官方风格指南的定位非常明确:它不是"最好的写法",而是"一致的写法"。官方文档原文引用 PEP 8 的经典表述——"愚蠢的一致性是小脑袋的妖怪(A foolish consistency is the hobgoblin of little minds)",并给出三层优先级:

  1. 与官方风格指南保持一致很重要;
  2. 与项目内部保持一致更重要;
  3. 与单个模块或函数内部保持一致最为重要。

因此,当项目自有风格与官方指南冲突时,项目特定风格指南优先;当遇到指南未覆盖的场景时,依赖作者的判断力、参考同类优秀示例,并勇于提问。这份指南是"演进中的文档",会随社区沉淀出更有用的约定而持续变化。从源码结构看,该指南的结构与许多推荐均源自 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 字符。需要换行时遵循四条规则:

  1. 第一个参数不要紧贴左括号;
  2. 只使用一个缩进级别;
  3. 每个参数独占一行;
  4. 终止符 ); 单独放在最后一行。

函数调用正确示例:

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 定义。按可见性分组,顺序固定为:

  1. constructor
  2. receive 函数(若存在)
  3. fallback 函数(若存在)
  4. external
  5. public
  6. internal
  7. private

在同一可见性分组内,将 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)

函数修饰符固定顺序:

  1. Visibility(可见性:external/public/internal/private)
  2. Mutability(可变性:view/pure/payable)
  3. Virtual
  4. Override
  5. 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 源文件中,顶层元素按以下顺序排列:

  1. Pragma 语句
  2. Import 语句
  3. Events
  4. Errors
  5. Interfaces
  6. Libraries
  7. Contracts

合约/库/接口内部顺序

每个 contract、library 或 interface 内部:

  1. Type declarations(类型声明,如 struct、enum)
  2. State variables(状态变量)
  3. Events
  4. Errors
  5. Modifiers
  6. 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 注释要求,每一处约定都以"提升可读性、降低协作成本、减少安全失误"为最终目标。把它作为团队的基线规范,在具体场景中结合项目自身约定灵活运用,就是最贴合官方意图的使用方式。

登录后查看全文
solidity