风格指南——Solidity中文文档（10）

时间  2019-11-21
标签 风格 指南 solidity 中文 文档 繁體版
原文   原文链接

image

写在前面：HiBlock区块链社区成立了翻译小组，翻译区块链相关的技术文档及资料，本文为Solidity文档翻译的第十部分《风格指南》，特发布出来邀请solidity爱好者、开发者作公开的审校，您能够添加微信baobaotalk_com，验证输入“solidity”，而后将您的意见和建议发送给咱们，也能够在文末“留言”区留言，有效的建议咱们会采纳及合并进下一版本，同时将送一份小礼物给您以示感谢。python

1

综述

本指南旨在约定 solidity 代码的编码规范。本指南是不断变化演进的，旧的、过期的编码规范会被淘汰， 而新的、有用的规范会被添加进来。api

许多项目会实施他们本身的编码风格指南。如遇冲突，应优先使用具体项目的风格指南。数组

本风格指南中的结构和许多建议是取自 python 的 pep8 style guide（https://www.python.org/dev/peps/pep-0008/） 。安全

本指南并 不是 以指导正确或最佳的 solidity 编码方式为目的。本指南的目的是保持代码的 一致性。 来自 python 的参考文档 pep8 。 很好地阐述了这个概念。微信

风格指南是关于一致性的。重要的是与此风格指南保持一致。但项目中的一致性更重要。一个模块或功能内的一致性是最重要的。 但最重要的是：知道何时不一致 —— 有时风格指南不适用。若有疑问，请自行判断。看看其余例子，并决定什么看起来最好。并应坚决果断地询问他人！app

2

代码结构

缩进ide

每一个缩进级别使用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）字符来帮助读者阅读代码。

折行时应该听从如下指引：

  • 第一个参数不该该紧跟在左括号后边

  • 用一个、且只用一个缩进

  • 每一个函数应该单起一行

  • 结束符号 ); 应该单独放在最后一行

函数调用

正确学法：

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);

赋值语句

正确写法：

thisIsALongNestedMapping[being][set][to_some_value] = someFunction(
   argument1,
   argument2,
   argument3,
   argument4

);

No:

thisIsALongNestedMapping[being][set][to_some_value] = someFunction(argument1,
                                                                  argument2,
                                                                  argument3,
                                                                  argument4);

事件定义和事件发生

正确写法：

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 编码。

Imports 规范

Import 语句应始终放在文件的顶部。

正确写法:

import "owned";

contract A {
   ...

}

contract B is owned {
   ...

}

错误写法:

contract A {
   ...

}

import "owned";

contract B is owned {
   ...

}

函数顺序

排序有助于读者识别他们能够调用哪些函数，并更容易地找到构造函数和 fallback 函数的定义。

函数应根据其可见性和顺序进行分组：

  • 构造函数

  • 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;}

你应该严格地标示全部函数的可见性，包括构造函数。

正确写法：

function explicitlyPublic(uint val) public {
   doSomething();

}

错误写法：

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();

}

多行输出参数和返回值语句应该听从 代码行的最大长度 一节的说明。

正确写法：

function thisFunctionNameIsReallyLong(
   address a,
   address b,
   address c

)
   public
   returns (
       address someAddressName,
       uint256 LongArgument,
       uint256 Argument
   )

{
   doSomething()

   return (
       veryLongReturnArg1,
       veryLongReturnArg2,
       veryLongReturnArg3
   );

}

错误写法：

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(); }

这些函数声明的准则旨在提升可读性。 由于本指南不会涵盖全部内容，做者应该自行做出最佳判断。

映射

待定

变量声明

数组变量的声明在变量类型和括号之间不该该有空格。

正确写法:

uint[] x;

错误写法:

uint [] x;

其余建议

  • 字符串应该用双引号而不是单引号。

正确写法:

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;

2

命名规范

当彻底采纳和使用命名规范时会产生强大的做用。 当使用不一样的规范时，则不会当即获取代码中传达的重要 元 信息。

这里给出的命名建议旨在提升可读性，所以它们不是规则，而是透过名称来尝试和帮助传达最多的信息。

最后，基于代码库中的一致性，本文档中的任何规范老是能够被（代码库中的规范）取代。

命名方式

为了不混淆，下面的名字用来指明不一样的命名方式。

  • b (单个小写字母)

  • B (单个大写字母)

  • lowercase （小写）

  • lower_case_with_underscores （小写和下划线）

  • UPPERCASE （大写）

  • UPPER_CASE_WITH_UNDERSCORES （大写和下划线）

  • CapitalizedWords (驼峰式，首字母大写）

  • mixedCase (混合式，与驼峰式的区别在于首字母小写！)

  • Capitalized_Words_With_Underscores (首字母大写和下划线)

..注意:: 当在驼峰式命名中使用缩写时，应该将缩写中的全部字母都大写。 所以 HTTPServerError 比 HttpServerError 好。

当在混合式命名中使用缩写时，除了第一个缩写中的字母小写（若是它是整个名称的开头的话）之外，其余缩写中的字母均大写。 所以 xmlHTTPRequest 比 XMLHTTPRequest 更好。

应避免的名称

  • l - el的小写方式

  • O - oh的大写方式

  • I - eye的大写方式

切勿将任何这些用于单个字母的变量名称。 他们常常难以与数字 1 和 0 区分开。

合约和库名称

合约和库名称应该使用驼峰式风格。好比：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。

避免命名冲突

  • single_trailing_underscore_

当所起名称与内建或保留关键字相冲突时，建议照此惯例在名称后边添加下划线。

通常建议

待定

延伸阅读：智能合约-Solidity官方文档（1）

安装Solidity编译器-Solidity官方文档（2）

根据例子学习Solidity-Solidity官方文档（3）

深刻理解Solidity之源文件及合约结构——Solidity中文文档（4）

安全考量——Solidity中文文档（5）

合约的元数据——Solidity中文文档（6）

应用二进制接口(ABI) 说明——Solidity中文文档（7）

使用编译器——Solidity中文文档（8）

Yul语言及对象说明——Solidity中文文档（9）

点击“阅读原文”便可查看完整中文文档

image

注：本文为solidity翻译的第十部分《风格指南》，特发布出来邀请solidity爱好者、开发者作公开的审校，您能够添加微信baobaotalk_com，验证输入“solidity”，而后将您的意见和建议发送给咱们，也可在文末“留言”区留言，或经过原文连接访问咱们的Github。有效的建议咱们会收纳并及时改进，同时将送一份小礼物给您以示感谢。

本文内容来源于HiBlock区块链社区翻译小组，感谢全体译者的辛苦工做。点击“阅读原文”便可查看完整中文文档。

线上课程推荐

线上课程：《8小时区块链智能合约开发实践》

培训讲师：《白话区块链》做者 蒋勇

课程原价：999元，现价 399元

更多福利：

  • @全部人，识别下图二维码转发课程邀请好友报名，便可得到报名费50%返利

  • @学员，报名学习课程并在规定时间内完成考试便可瓜分10000元奖金

image

相关文章
相关标签/搜索
每日一句
    每一个你不满意的现在，都有一个你没有努力的曾经。
本站公众号
   欢迎关注本站公众号,获取更多信息
联系我们 最近搜索 最新文章 沪ICP备13005482号-10 MyBatis教程 SQL 教程 MySQL教程 Java 教程 Thymeleaf 教程 Hibernate教程 Spring教程 Redis教程