Solidity - 风格指南

---

样式指南有助于保持代码布局一致并使代码更具可读性。以下是使用 Solidity 编写合约时的最佳实践。

代码布局

• 缩进- 使用 4 个空格而不是制表符来保持缩进级别。避免将空格与制表符混合。

• 两个空行规则- 在两个合同定义之间使用 2 个空行。

pragma solidity ^0.5.0;

contract LedgerBalance {
   //...
}
contract Updater {
   //...
}

• 一个空行规则- 在两个函数之间使用 1 个空行。如果只是声明，则不需要空行。

pragma solidity ^0.5.0;

contract A {
   function balance() public pure;
   function account() public pure;
}
contract B is A {
   function balance() public pure {
      // ...
   }
   function account() public pure {
      // ...
   }
}

• 最大行长度- 单行不应超过 79 个字符，以便读者可以轻松解析代码。

• 包装规则- 第一个参数位于新行中，不带左括号。每个参数使用单缩进。终止元素）；应该是最后一个。

function_with_a_long_name(
   longArgument1,
   longArgument2,
   longArgument3
);
variable = function_with_a_long_name(
   longArgument1,
   longArgument2,
   longArgument3
);
event multipleArguments(
   address sender,
   address recipient,
   uint256 publicKey,
   uint256 amount,
   bytes32[] options
);
MultipleArguments(
   sender,
   recipient,
   publicKey,
   amount,
   options
);

• 源代码编码- 最好使用 UTF-8 或 ASCII 编码。

• 导入- 导入语句应放置在文件顶部，紧接在 pragma 声明之后。

• 函数顺序- 函数应根据其可见性进行分组。

pragma solidity ^0.5.0;

contract A {
   constructor() public {
      // ...
   }
   function() external {
      // ...
   }

   // External functions
   // ...

   // External view functions
   // ...

   // External pure functions 
   // ...

   // Public functions
   // ...

   // Internal functions
   // ...

   // Private functions
   // ...
}

• 避免额外的空格- 避免紧邻括号、方括号或大括号内的空格。

• 控制结构- 大括号应与声明在同一行打开。关闭在自己的行上，保持相同的缩进。使用带左大括号的空格。

pragma solidity ^0.5.0;

contract Coin {
   struct Bank {
      address owner;
      uint balance;
   }
}
if (x < 3) {
   x += 1;
} else if (x > 7) {
   x -= 1;
} else {
   x = 5;
}
if (x < 3)
   x += 1;
else
   x -= 1;

• 函数声明- 对大括号使用上述规则。始终添加可见性标签。可见性标签应首先出现在任何自定义修饰符之前。

function kill() public onlyowner {
   selfdestruct(owner);
}

• 映射- 声明映射变量时避免空格。

mapping(uint => uint) map;
mapping(address => bool) registeredAddresses;
mapping(uint => mapping(bool => Data[])) public data;
mapping(uint => mapping(uint => s)) data;

• 变量声明- 声明数组变量时避免空格。

uint[] x;  // not unit [] x;

• 字符串声明- 使用双引号而不是单引号来声明字符串。

str = "foo";
str = "Hamlet says, 'To be or not to be...'";

布局顺序

元素应按以下顺序布局。

• 杂注语句

• 进口声明

• 接口

• 图书馆

• 合约

在接口、库或合约中，顺序应为 -

• 类型声明

• 状态变量

• 活动

• 功能

命名约定

• 合同和库应使用 CapWords 样式命名。例如，智能合约、所有者等。

• 合同和库名称应与其文件名匹配。

• 如果一个文件中有多个合约/库，请使用核心合约/库的名称。

拥有.sol

pragma solidity ^0.5.0;

// Owned.sol
contract Owned {
   address public owner;
   constructor() public {
      owner = msg.sender;
   }
   modifier onlyOwner {
      //....
   }
   function transferOwnership(address newOwner) public onlyOwner {
      //...
   }
}

国会.sol

pragma solidity ^0.5.0;

// Congress.sol
import "./Owned.sol";

contract Congress is Owned, TokenRecipient {
   //...
}

• 结构名称

  - 使用像 SmartCoin 这样的 CapWords 风格。

• 事件名称

  - 使用 CapWords 风格，如 Deposit、AfterTransfer。

• 函数名称

  - 使用混合大小写样式，如initiateSupply。

• 局部变量和状态变量

  - 使用混合大小写样式，如creatorAddress、supply。

• 常数

  - 使用所有大写字母和下划线来分隔单词，例如 MAX_BLOCKS。

• 修饰符名称

  - 使用 mixCase 样式，如 onlyAfter。

• 枚举名称

  - 使用像 TokenGroup 这样的 CapWords 样式。