本指南旨在约定 solidity 代码的编码规范。本指南是不断变化演进的,旧的、过时的编码规范会被淘汰, 而新的、有用的规范会被添加进来。
许多项目会实施他们自己的编码风格指南。如遇冲突,应优先使用具体项目的风格指南。
本风格指南中的结构和许多建议是取自 python 的 pep8 style guide 。
本指南并 不是 以指导正确或最佳的 solidity 编码方式为目的。本指南的目的是保持代码的 一致性 。 来自 python 的参考文档 pep8 。 很好地阐述了这个概念。
风格指南是关于一致性的。重要的是与此风格指南保持一致。但项目中的一致性更重要。一个模块或功能内的一致性是最重要的。 但最重要的是:知道什么时候不一致 —— 有时风格指南不适用。如有疑问,请自行判断。看看其他例子,并决定什么看起来最好。并应毫不犹豫地询问他人!
每个缩进级别使用4个空格。
在 solidity 源码中合约声明之间留出两个空行。
正确写法:
contract A {
...
}
contract B {
...
}
contract C {
...
}
错误写法:
contract A {
...
}
contract B {
...
}
contract C {
...
}
在一个合约中的函数声明之间留有一个空行。
在相关联的各组单行语句之间可以省略空行。(例如抽象合约的 stub 函数)。
正确写法:
contract A {
function spam() public;
function ham() public;
}
contract B is A {
function spam() public {
...
}
function ham() public {
...
}
}
错误写法:
contract A {
function spam() public {
...
}
function ham() public {
...
}
}
基于 PEP 8 recommendation ,将代码行的字符长度控制在 79(或 99)字符来帮助读者阅读代码。
折行时应该遵从以下指引:
函数调用
Yes:
thisFunctionCallIsReallyLong(
longArgument1,
longArgument2,
longArgument3
);
No:
thisFunctionCallIsReallyLong(longArgument1,
longArgument2,
longArgument3
);
thisFunctionCallIsReallyLong(longArgument1,
longArgument2,
longArgument3
);
thisFunctionCallIsReallyLong(
longArgument1, longArgument2,
longArgument3
);
thisFunctionCallIsReallyLong(
longArgument1,
longArgument2,
longArgument3
);
thisFunctionCallIsReallyLong(
longArgument1,
longArgument2,
longArgument3);
赋值语句
Yes:
thisIsALongNestedMapping[being][set][to_some_value] = someFunction(
argument1,
argument2,
argument3,
argument4
);
No:
thisIsALongNestedMapping[being][set][to_some_value] = someFunction(argument1,
argument2,
argument3,
argument4);
事件定义和事件发生
Yes:
event LongAndLotsOfArgs(
adress sender,
adress recipient,
uint256 publicKey,
uint256 amount,
bytes32[] options
);
LongAndLotsOfArgs(
sender,
recipient,
publicKey,
amount,
options
);
No:
event LongAndLotsOfArgs(adress sender,
adress recipient,
uint256 publicKey,
uint256 amount,
bytes32[] options);
LongAndLotsOfArgs(sender,
recipient,
publicKey,
amount,
options);
首选 UTF-8 或 ASCII 编码。
Import 语句应始终放在文件的顶部。
正确写法:
import "owned";
contract A {
...
}
contract B is owned {
...
}
错误写法:
contract A {
...
}
import "owned";
contract B is owned {
...
}
排序有助于读者识别他们可以调用哪些函数,并更容易地找到构造函数和 fallback 函数的定义。
函数应根据其可见性和顺序进行分组:
在一个分组中,把 view 和 pure 函数放在最后。
正确写法:
contract A {
function A() public {
...
}
function() public {
...
}
// External functions
// ...
// External functions that are view
// ...
// External functions that are pure
// ...
// Public functions
// ...
// Internal functions
// ...
// Private functions
// ...
}
错误写法:
contract A {
// External functions
// ...
// Private functions
// ...
// Public functions
// ...
function A() public {
...
}
function() public {
...
}
// Internal functions
// ...
}
在以下情况下避免无关的空格:
除单行函数声明外,紧接着小括号,中括号或者大括号的内容应该避免使用空格。
正确写法:
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;
long_variable = 3;
错误写法:
x = 1;
y = 2;
long_variable = 3;
fallback 函数中不要包含空格:
正确写法:
function() public {
...
}
错误写法:
function () public {
...
}
用大括号表示一个合约,库、函数和结构。 应该:
正确写法:
contract Coin {
struct Bank {
address owner;
uint balance;
}
}
错误写法:
contract Coin
{
struct Bank {
address owner;
uint balance;
}
}
对于控制结构 if, else, while, for 的实施建议与以上相同。
另外,诸如 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 块, else 应该是与 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) {
x += 1;
}
else {
x -= 1;
}
对于简短的函数声明,建议函数体的开括号与函数声明保持在同一行。
闭大括号应该与函数声明的缩进级别相同。
开大括号之前应该有一个空格。
正确写法:
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;}
你应该严格地标示所有函数的可见性,包括构造函数。
Yes:
function explicitlyPublic(uint val) public {
doSomething();
}
No:
function implicitlyPublic(uint val) {
doSomething();
}
函数的可见性修饰符应该出现在任何自定义修饰符之前。
正确写法:
function kill() public onlyowner {
selfdestruct(owner);
}
错误写法:
function kill() onlyowner public {
selfdestruct(owner);
}
对于长函数声明,建议将每个参数独立一行并与函数体保持相同的缩进级别。闭括号和开括号也应该 独立一行并保持与函数声明相同的缩进级别。
正确写法:
function thisFunctionHasLotsOfArguments(
address a,
address b,
address c,
address d,
address e,
address f
)
public
{
doSomething();
}
错误写法:
function thisFunctionHasLotsOfArguments(address a, address b, address c,
address d, address e, address f) public {
doSomething();
}
function thisFunctionHasLotsOfArguments(address a,
address b,
address c,
address d,
address e,
address f) public {
doSomething();
}
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();
}
错误写法:
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();
}
function thisFunctionNameIsReallyLong(address x, address y, address z)
public
onlyowner
priced
returns (address) {
doSomething();
}
多行输出参数和返回值语句应该遵从 代码行的最大长度 一节的说明。
Yes:
function thisFunctionNameIsReallyLong(
address a,
address b,
address c
)
public
returns (
address someAddressName,
uint256 LongArgument,
uint256 Argument
)
{
doSomething()
return (
veryLongReturnArg1,
veryLongReturnArg2,
veryLongReturnArg3
);
}
No:
function thisFunctionNameIsReallyLong(
address a,
address b,
address c
)
public
returns (address someAddressName,
uint256 LongArgument,
uint256 Argument)
{
doSomething()
return (veryLongReturnArg1,
veryLongReturnArg1,
veryLongReturnArg1);
}
对于继承合约中需要参数的构造函数,如果函数声明很长或难以阅读,建议将基础构造函数像多个修饰符的风格那样 每个下沉到一个新行上书写。
正确写法:
contract A is B, C, D {
function A(uint param1, uint param2, uint param3, uint param4, uint param5)
B(param1)
C(param2, param3)
D(param4)
public
{
// do something with param5
}
}
错误写法:
contract A is B, C, D {
function A(uint param1, uint param2, uint param3, uint param4, uint param5)
B(param1)
C(param2, param3)
D(param4)
public
{
// do something with param5
}
}
contract A is B, C, D {
function A(uint param1, uint param2, uint param3, uint param4, uint param5)
B(param1)
C(param2, param3)
D(param4)
public {
// do something with param5
}
}
当用单个语句声明简短函数时,允许在一行中完成。
允许:
function shortFunction() public { doSomething(); }
这些函数声明的准则旨在提高可读性。 因为本指南不会涵盖所有内容,作者应该自行作出最佳判断。
待定
正确写法:
str = "foo";
str = "Hamlet says, 'To be or not to be...'";
错误写法:
str = 'bar';
str = '"Be yourself; everyone else is already taken." -Oscar Wilde';
正确写法:
x = 3;
x = 100 / 10;
x += 3 + 4;
x |= y && z;
错误写法:
x=3;
x = 100/10;
x += 3+4;
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;
当完全采纳和使用命名规范时会产生强大的作用。 当使用不同的规范时,则不会立即获取代码中传达的重要 元 信息。
这里给出的命名建议旨在提高可读性,因此它们不是规则,而是透过名称来尝试和帮助传达最多的信息。
最后,基于代码库中的一致性,本文档中的任何规范总是可以被(代码库中的规范)取代。
为了避免混淆,下面的名字用来指明不同的命名方式。
合约和库名称应该使用驼峰式风格。比如:SimpleToken,SmartBank,CertificateHashRepository,Player。
结构体名称应该使用驼峰式风格。比如:MyCoin,Position,PositionXY。
事件名称应该使用驼峰式风格。比如:Deposit,Transfer,Approval,BeforeTransfer,AfterTransfer。
函数名称不同于结构,应该使用混合式命名风格。比如:getBalance,transfer,verifyOwner,addMember,changeOwner。
函数参数命名应该使用混合式命名风格。比如:initialSupply,account,recipientAddress,senderAddress,newOwner。 在编写操作自定义结构的库函数时,这个结构体应该作为函数的第一个参数,并且应该始终命名为 self。
使用混合式命名风格。比如:totalSupply,remainingSupply,balancesOf,creatorAddress,isPreSale,tokenExchangeRate。
常量应该全都使用大写字母书写,并用下划线分割单词。比如:MAX_BLOCKS,TOKEN_NAME,TOKEN_TICKER,CONTRACT_VERSION。
使用混合式命名风格。比如:onlyBy,onlyAfter,onlyDuringThePreSale。
在声明简单类型时,枚举应该使用驼峰式风格。比如:TokenGroup,Frame,HashStyle,CharacterLocation。
待定