Solidity - 风格指南简介

2025年5月27日 | 阅读 13 分钟

Solidity 是一种用于编写可执行智能合约的高级计算机语言，这些合约部署在以太坊网络上。这些合约随后用于创建不同的数字应用程序，包括投票应用程序、去中心化组织、数据存储应用、产权注册等，以及许多其他应用。

与许多其他编程语言不同，Solidity 还支持高级面向对象编程概念，如继承、构造函数、映射、封装、数组、结构体等。它的出现旨在推广以太坊技术，并在世界各地创造数字商业机会。在使用任何语言编写代码时，了解其风格指南同样重要。代码布局、命名约定、不同的缩进、行限制、变量和函数是任何编程语言（包括 Solidity）的重要方面。采纳合适的风格指南可以使您的代码更具可读性和用户友好性，因为它定义了空格、花括号、行限制、导入等的使用规则。

在本教程中，我们将涵盖各种主题，从代码布局开始，然后是编写正确代码段的适当指南、命名约定以及 Solidity 中的 NatSpec 声明。

代码布局

定义任何编程语言的布局至关重要，因为它能使您的代码具有可读性且结构良好。因此，要精通 Solidity，维护其代码布局是必不可少的。良好的代码布局有助于程序员维护他们的智能合约，使其更具用户友好性和易于理解。以下是一些有助于在整个 Solidity 智能合约中保持理想代码布局的指南：

1. 缩进

使用 4 个空格进行缩进而不是使用制表符被认为是一种良好的实践。下面提供了为了更好地理解而编写的正确和错误的代码段。

正确的缩进实践的布局

//SPDX-License-Identifier: MIT
pragma solidity ^0.8.0;

// Right method to specify correct the indentation in solidity
contract x1 {
   // ... text to be added here
}
contract x2 {
   // ... text to be added here
}
contract x3 {
   // ... text to be added here
}

错误的缩进实践的布局

//SPDX-License-Identifier: MIT
pragma solidity ^0.8.0;

// Wrong way to specify the wrong indentation for smart contracts
contract x1 {  // ... text to be added here
}
contract x2 {   // ... text to be added here
}
contract x3 {   // ... text to be added here
}

2. 行长度限制为 120 个字符

有时，您的代码会超出 120 个字符的限制，这会使代码显得不专业且臃肿。在这种情况下，为了保持专业性，建议将代码分解成多行。采用这种方法将使您的智能合约更具可读性，即使在较小的屏幕上。

下面提供了为了更好地理解而编写的正确和错误的代码段。

正确的处理方式的布局

//SPDX-License-Identifier: MIT
pragma solidity ^0.8.0;
contract x1 {
// right approach
theFunctionWithLongContent(
   progVariable1,
    progVariable2,
   progVariable3,
);
}

错误的几种处理方式的布局

//SPDX-License-Identifier: MIT
pragma solidity ^0.8.0;
contract x1 {
// Wrong approaches
theFunctionWithLongContent (progVariable1,
                             progVariable2,
                             progVariable3
);
}

//SPDX-License-Identifier: MIT
pragma solidity ^0.8.0;
contract x1 {
theFunctionWithLongContent (progVariable1,
   progVariable2,
   progVariable3
);
}

//SPDX-License-Identifier: MIT
pragma solidity ^0.8.0;
contract x1 {
theFunctionWithLongContent (
   progVariable1, progVariable2,
   progVariable3
);
}

3. 花括号

在 Solidity 中，花括号用于界定函数、控制结构和合约的语法。您始终应将开花括号放在代码声明的同一行，并将闭花括号放在新的一行。

下面提供了为了更好地理解而编写的正确和错误的代码段。

花括号正确实践的布局

//SPDX-License-Identifier: MIT
pragma solidity ^0.8.0;
// right practice for using curly braces
import "./Owned.sol";
contract x1 {
   // ... text to be added here
}

花括号错误实践的布局

//SPDX-License-Identifier: MIT
pragma solidity ^0.8.0;
// wrong practice for using curly braces
import "./Owned.sol";
contract x1
{
// .. text to be added here
}

4. 函数之间的空行

在函数末尾和下一个函数开头之间添加一个空行。下面提供了为了更好地理解而编写的正确和错误的代码段。

函数之间使用空行的正确实践的布局

//SPDX-License-Identifier: MIT
pragma solidity ^0.8.0;
// right practice for using blank line between functions
abstract contract x1 {
   function example() public virtual pure;
   function example1() public virtual pure;
}
// inheritance the properties of parent class x1
contract x2 is x1 {
   function example() public pure override {
       // ... text to be added here
   }
   function example1() public pure override {
       // ... text to be added here
   }

函数之间使用空行的错误实践的布局

//SPDX-License-Identifier: MIT
pragma solidity ^0.8.0;
// wrong practice for using blank line between functions
abstract contract x1 {
   function example() public virtual pure;
   function example1() public virtual pure;
}
// inheritance the properties of parent class x1
contract x2 is x1 {
   function example() public pure override {
       // ... text to be added here
   }

   function example1() public pure override {
       // ... text to be added here
   }

5. 函数内部行之间的空行

始终建议在函数内编写的不同行代码之间添加一个空行（例如，在变量声明和函数调用之间）。下面提供了为了更好地理解而编写的正确和错误的代码段。

函数内部代码块中使用空行的正确方法的布局

//SPDX-License-Identifier: MIT
pragma solidity ^0.8.0;
abstract contract x1 {
function example() public virtual pure;
// right practice for using blank line between functions
uint256 public varVal;
doSomething();

函数内部代码块中使用空行的不正确方法的布局

//SPDX-License-Identifier: MIT
pragma solidity ^0.8.0;
abstract contract x1 {
function example() public virtual pure;
// wrong practice for using blank line between functions

uint256 public varVal;

doSomething();

6. 运算符和操作数之间的单个空格

在智能合约中使用任何特殊字符时，请始终记住不要添加任何空格。尽管您只能在运算符和操作数之间添加一个空格。下面提供了为了更好地理解而编写的正确和错误的代码段。

运算符和操作数之间添加单个空格的正确实践的布局。

//SPDX-License-Identifier: MIT
pragma solidity ^0.8.0;
contract x1 {
// right practice to add space between operators and operands
unit[] val1;
val1 = 70;
val1 = 55 / 11;
val1 += 43 + 54;

运算符和操作数之间添加单个空格的错误实践的布局。

//SPDX-License-Identifier: MIT
pragma solidity ^0.8.0;
contract x1 {
// wrong practice to add space between operators and operands
unit[] val1;
val1=70;
val1=55 / 11;
val1+=43 + 54;

7. 在保留关键字之间不加空格

在智能合约中使用任何保留关键字时，请始终记住不要在它们之间添加任何空格。下面提供了为了更好地理解而编写的正确和错误的代码段。

声明保留关键字的正确实践的布局

//SPDX-License-Identifier: MIT
pragma solidity ^0.8.0;
contract x1 {
// right practice to declare reserved keywords
mapping(uint => uint) map;
mapping(address => bool) yourRegisteredAddress;
mapping(uint => mapping(uint => s)) val;

声明保留关键字的错误实践的布局

//SPDX-License-Identifier: MIT
pragma solidity ^0.8.0;
contract x1 {
// wrong practice to declare reserved keywords
papping (uint => uint) map;
mapping (address => bool)        yourRegisteredAddress;
mapping(uint => mapping(uint => s)) val;

8. 导入

在声明多个导入语句时，请始终记住按字母顺序对其进行排序。文件名应始终不同，因为如果您重复相同的导入名称，将会返回错误。使用 import "./filename"; 语法来表示外部合约依赖。

声明导入语句的正确实践的布局

// Right Practice
import "./nameofyourfile1";
import "./nameofyourfile2";
import "./nameofyourfile3";

声明导入语句的正确实践的布局

// Wrong Practice
import "./nameofyourfile1";
import "./ nameofyourfile1";
import "./ nameofyourfile3";
import "./ nameofyourfile2";

9. 函数顺序

在定义任何函数的元素时，建议按以下方式排列函数：

首先定义构造函数。
然后声明常量函数。
接下来，定义所有公共状态修改函数。
接下来，定义内部状态修改函数。
最后，声明所有私有状态修改函数。

下面提供了为了更好地理解而编写的正确和错误的代码段。

定义函数顺序的正确实践的布局

// Right Practice
contract A1 {
constructor() public { ... text to be written here}
function constantFuncName1() public constant returns (...) 
{ ... text to be written here }
function constantFuncName2() public constant returns (...) 
{ ... text to be written here }
function publicFuncName1() public 
{ ... text to be written here }
function publicFuncName2() public
 { ... text to be written here }
function internalFuncName1() internal 
{ ... text to be written here }
function internalFuncName2() internal 
{ ... text to be written here }
function privateFuncName1() private
 { ... text to be written here }
function privateFuncName2() private
 { ... text to be written here }
}

定义函数顺序的错误实践的布局

// Wrong Practice
contract A1 {
constructor() public { ... text to be written here}
function constantFuncName1() public constant returns (...) { ... text to be written here }
function constantFuncName2() public constant returns (...) { ... text to be written here }
function publicFuncName1() public { ... text to be written here }
function publicFuncName2() public { ... text to be written here }
function internalFuncName1() internal { ... text to be written here }
function internalFuncName2() internal { ... text to be written here }
function privateFuncName1() private { ... text to be written here }
function privateFuncName2() private { ... text to be written here }
}

10. 表达式中的空格

我们经常在智能合约中使用空格来分隔合约的不同元素，以使文本更清晰。这增加了代码的可读性。在二元和三元运算符（例如 +、-、? :）周围对齐适当的空格。

下面提供了为了更好地理解而编写的正确和错误的代码段。

表达式中使用空格的正确实践的布局

// Right Practice
uint val1 = (x + y) * z;
uint val2 = (x > y) ? x : y;

表达式中使用空格的错误实践的布局

// Wrong Practice
uint val1=(x+y)*z;
uint val2=(x>y)?x:y;

11. 函数声明

函数是可执行的代码块，其中包含合约中的必要业务逻辑。声明函数的最佳方法是使用 function 关键字，后跟函数名称、参数以及一对括号 ()，以及用花括号 {} 括起来的函数体。函数应始终使用不同的名称声明，以避免任何混淆。

下面提供了为了更好地理解而编写的正确和错误的代码段。

使用函数声明的正确实践的布局

// Right Practice
//SPDX-License-Identifier: MIT
pragma solidity ^0.8.0;
contract x1 {
function sum(uint x, uint y) public returns (uint) {
return x + y;
}

使用函数声明的错误实践的布局

// Wrong Practice
//SPDX-License-Identifier: MIT
pragma solidity ^0.8.0;
contract x1 {
function sum(uint x, uint y) {
return x + y;
}
function sum(uint x, uint y) public returns (uint) {
return x + y;
}

12. 变量声明

变量声明是任何编程语言不可或缺的一部分。该过程是声明变量，后跟适当的变量名和值类型。为了提高可读性，请将变量声明得尽可能靠近其实际使用位置。

下面提供了为了更好地理解而编写的正确和错误的代码段。

在 Solidity 代码中声明变量的正确实践的布局

// Right Practice 
//SPDX-License-Identifier: MIT
pragma solidity ^0.8.0;
contract x1 {
function example() public {
uint x = 10;
uint y = 20;
uint z = x + y;
}

在 Solidity 代码中声明变量的正确实践的布局

// Wrong Practice 
//SPDX-License-Identifier: MIT
pragma solidity ^0.8.0;
contract x1 {
function example() public {
uint x;
x = 10;
uint y = 20;
uint z = x + y;
}

13. 在智能合约中应避免的名称

建议不要使用任何关键字（例如 contract、function 等）作为变量、函数或合约的名称。避免使用单个字母的名称，循环索引除外。

下面提供了为了更好地理解而编写的正确和错误的代码段。

在 Solidity 代码中声明变量的正确实践的布局

// Right Practice 
//SPDX-License-Identifier: MIT
pragma solidity ^0.8.0;
contract x1 {
function sum(uint x, uint y) public returns (uint) { ... }
for (uint i = 0; i < 10; i++) { ...  text to be added here}

在 Solidity 代码中声明变量的错误实践的布局

// Wrong Practice 
//SPDX-License-Identifier: MIT
pragma solidity ^0.8.0;
contract x1 {
function Sum(uint x, uint y) public returns (uint) { ... }
for (uint i = 0; i < 10; i++) { ... text to be added }

合约布局顺序

布局顺序定义为用户定义 Solidity 合约所有不同元素的首选顺序。遵循推荐的顺序可以使您的代码用户友好且可读。以下是编写 Solidity 智能合约时应遵循的布局：

1. Solidity Pragma 语句

pragma 语句是 Solidity 中的一个指令，应包含在代码的开头，因为它定义了智能合约的版本。没有 pragma 语句，编译器将无法编译代码；因此，包含它以使其在以太坊虚拟机 (EVM) 上精确运行非常重要。

2. Import 语句

Import 语句用于在您的合约中包含来自其他文件或库的代码。在使用任何预定义功能时，需要 Import 语句。

3. 合约和库定义

这是一个关键字，用于定义可以进一步部署在以太坊网络上的智能合约代码。它是一组函数和变量，它们组合在一起构成了合约，以及它将如何运作的逻辑。

4. 全局变量

Solidity 提供了广泛的数据类型供智能合约使用。这有助于它们满足更广泛的受众，并处理各种类型的输入查询。

在合约开头声明任何全局变量。将相关变量分组在一起，并首先声明常量，然后声明在合约执行期间将修改的变量，这是一种良好的实践。

5. 构造函数

构造函数被定义为一个特殊函数，可以在每次部署智能合约时调用一次。它是您合约中首先初始化的内容。因此，它写在声明全局变量之后。

6. 回退函数 (Fallback Function)

这是一个未命名的函数，当函数签名与任何可用函数不匹配时会被触发。当智能合约想要从钱包接收资金时，这非常有用。回退函数应始终标记为 external。

7. 变量声明

变量用于在合约中存储数据。在 Solidity 中，变量必须声明类型，例如无符号整数的 uint256 或以太坊地址的 address。

8. 公共函数和外部函数定义

在变量之后，始终声明所有公共函数和外部函数。公共函数是合约接口的一部分。它们可以从内部调用，也可以通过消息调用。外部函数可以通过交易从其他合约调用。它们是合约接口的一部分。

9. 内部函数

内部函数在公共函数和外部函数之后声明。它们只能从当前合约或从派生自它的合约访问。这是状态变量的默认可见性级别。它们不会创建实际的 EVM 调用。

10. 私有函数

私有函数仅对定义它们的合约可见，在派生合约中不可见。它们在最后声明。当程序员希望封装或隐藏敏感内容免受外部参与者访问时，使用它们。

11. Solidity 中的事件

Solidity 中的事件用于在以太坊虚拟机中记录事件和交易。当触发外部操作或通知我们合约中发生的任何更改或事件时，它们非常有用。始终建议在函数之后声明所有事件。事件的声明方式与函数相同，但开头使用 event 关键字，并且没有函数体。与函数不同，您可以声明参数（可以是任何类型）。

命名约定

每种语言都必须定义一套规则来编写程序变量、函数、事件和其他重要单元的名称。Solidity 也有自己的一套规则，即用于编写代码并使其更具可读性和用户友好性的命名约定。

以下是代码中的命名约定指南：

对于变量和函数的命名，始终使用 **CamelCase**，即第一个单词小写，第二个单词首字母大写。例如：javaTPoint
要定义您的合约和结构体名称，请使用 **PascalCase**。在这种情况下，名称中的每个单词都以大写字母开头，并且单词之间没有空格或下划线。例如：JavaTPoint
为变量和函数使用描述性的小写名称（例如，totalSupply 而不是 ts）。
要声明私有变量，请使用前导下划线。例如：_your PrivateVariables。
为了轻松识别布尔变量，建议使用前导“is”或“has”关键字来声明它们。例如：isActive 或 hasData。
声明常量使用全大写名称，并确保定义的名称是相关的且有意义的。例如：ZERO_DATA
切勿为变量使用任何缩写和单个字母的名称，除了常见的名称，如“id”和“num”。
切勿将任何保留关键字用作变量的名称。
为了确保代码的清晰性，请为事件使用描述性且有意义的名称，并加上“Log.”前缀。
为了确保变量和函数名称的可读性，请编写有意义的名称来描述其目的。
为了确保代码的清晰性，请为函数参数使用描述性且有意义的名称，以说明其用途。
要编写用户友好的代码，建议为局部变量和状态变量编写名称。

下面提供了为了更好地理解而编写的正确和错误的代码段。

//SPDX-License-Identifier: MIT
pragma solidity ^0.8.0;
contract x1 {
// declaring the Constants of your variable with ALL_CAPS
uint public constant MIN_DATA_VALUE = 450;
uint256 public constant MAX_DATA_VALUE = 909;
// declaring the Variables with CamelCase
uint256 public addData;
address public yourAddress;
mapping(yourAddress => uint256) public balances;
...

NatSpec

在 Solidity 中，NatSpec 是用 Markdown 格式编写的注释，用于记录您的代码，以便程序更容易被其他读者理解。它代表自然语言规范。可以通过以太坊 NatSpec 标准 JSON 接口访问 NatSpec 文档。

编写 Solidity 中的 NatSpec 注释有两个规则：

1. 使用双斜杠（//）在程序中声明单行 NatSpec 注释。

2. 使用（“/**.....*/”）声明多行 NatSpec 注释。以下是示例：

/**
@notice Adding two number and returning the sum as result
@param Represents the first parameter to add the numbers
@param Parameter2 Description of parameter2
@return the sum of two parameters
*/

下一主题Solidity-break-and-continue-statements

Solidity - 风格指南简介

代码布局

1. 缩进

2. 行长度限制为 120 个字符

3. 花括号

4. 函数之间的空行

5. 函数内部行之间的空行

6. 运算符和操作数之间的单个空格

7. 在保留关键字之间不加空格

8. 导入

9. 函数顺序

10. 表达式中的空格

11. 函数声明

12. 变量声明

13. 在智能合约中应避免的名称

合约布局顺序

1. Solidity Pragma 语句

2. Import 语句

3. 合约和库定义

4. 全局变量

5. 构造函数

6. 回退函数 (Fallback Function)

7. 变量声明

8. 公共函数和外部函数定义

9. 内部函数

10. 私有函数

11. Solidity 中的事件

命名约定

NatSpec

联系信息

关注我们

教程

面试题

在线编译器

Python

Java

.Net Framework

AI, ML and Data Science

Cloud Technology

B.Tech and MCA

Web Technology

PHP

Software Testing

Technical Interview

Java Interview

Python

Web Interview

Database Interview

B.Tech / MCA

Important Interview

Software Testing Interview

Company Interviews

Online Compilers

Multiple Choice Questions

Solidity 教程

Solidity - 风格指南简介

代码布局

1. 缩进

2. 行长度限制为 120 个字符

3. 花括号

4. 函数之间的空行

5. 函数内部行之间的空行

6. 运算符和操作数之间的单个空格

7. 在保留关键字之间不加空格

8. 导入

9. 函数顺序

10. 表达式中的空格

11. 函数声明

12. 变量声明

13. 在智能合约中应避免的名称

合约布局顺序

1. Solidity Pragma 语句

2. Import 语句

3. 合约和库定义

4. 全局变量

5. 构造函数

6. 回退函数 (Fallback Function)

7. 变量声明

8. 公共函数和外部函数定义

9. 内部函数

10. 私有函数

11. Solidity 中的事件

命名约定

NatSpec

相关帖子

Solidity View 和 Pure 函数

Solidity 如何工作

Solidity 中的错误处理

智能合约安全考虑

Solidity 函数修饰符

Solidity 注释

Solidity 数据类型

Solidity 中的 struct 是什么

Solidity Break 和 Continue 语句

Solidity 抽象合约

订阅 Tpoint Tech

联系信息

关注我们

教程

面试题

在线编译器