智能合約最佳實踐 之 Solidity 編碼規範
命名規範
避免使用
小寫的l,大寫的I,大寫的O 應該避免在命名中單獨出現,因為很容易產生混淆。
合約、庫、事件、枚舉及結構體命名
合約、庫、事件及結構體命名應該使用單詞首字母大寫的方式,這個方式也稱為:帕斯卡命名法或大駝峰式命名法,比如:SimpleToken, SmartBank, CertificateHashRepository,Player。
函數、參數、變量及修飾器
函數、參數、變量及修飾器應該使用首單詞小寫後面單詞大寫的方式,這個方式也稱為:(小)駝峰式命名法,是一種混合大小寫的方式,如:
- 函數名應該如:getBalance,transfer,verifyOwner,addMember。
- 參數和變量應該如:initialSupply,senderAddress,account,isPreSale。
- 修飾器應該如:onlyAfter,onlyOwner。
代碼格式相關
縮進
使用空格(spaces)而不是Tab, 縮進應該是4個空格
空行
合約之間應該有空行,例如:
contract A {
...
}
contract B {
...
}
contract C {
...
}
而不是使用:
contract A { ... } contract B { ... } contract C { ... }
- 函數之間應該有空行,例如:
contract A {
function spam() public {
...
}
function ham() public {
...
}
}
沒有實現的話,空行可以省去,如:
contract A {
function spam() public;
function ham() public;
}
而不是:
contract A { function spam() public { ... } function ham() public { ... } }
左括號應該跟定義在一行
定義包括合約定義、函數定義、庫定義、結構體定義等等,例如推薦使用:
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
}));
表達式內的空格
-
一個單行的表達裏,在小括號、中括號、大括號裏應該避免不必要的空格,例如推薦使用:
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;
-
回退函數不應該有空格,例如推薦使用:
function() public { ... }
而不是:
function () public { ... }
控制每一行長度
每行不應該太長,最好在79(或99)個字符以內,函數的參數應該是單獨的行,且只有一個縮進,例如推薦的方式是:
thisFunctionCallIsReallyLong(
longArgument1,
longArgument2,
longArgument3
);
而不是:
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
);
而不是:
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
);
而不是:
event LongAndLotsOfArgs(adress sender,
adress recipient,
uint256 publicKey,
uint256 amount,
bytes32[] options);
LongAndLotsOfArgs(sender,
recipient,
publicKey,
amount,
options);
文件編碼格式
推薦使用utf-8 及 ASCII 編碼
引入文件應該在最上方
建議使用:
import "owned";
contract A {
...
}
contract B is owned {
...
}
而不是:
contract A {
...
}
import "owned";
contract B is owned {
...
}
函數編寫規範
函數的順序
在編寫函數的時候,應該讓大家容易找到構造函數,回退函數,官方推薦的的函數順序是:
- 構造函數
- 回退函數 (如果有)
- 外部函數(external)
- 公有函數(public)
- 內部函數(internal)
- 私有函數(private)
同一類函數時,constant函數放在後面, 例如推薦方式為:
contract A {
// 構造函數
function A() public {
...
}
// 回退函數
function() public {
...
}
// 外部函數
// ...
// 帶有constant 外部函數
// ...
// 公有函數
// ...
// 內部函數
// ...
// 私有函數
// ...
}
而不是下面的函數順序:
contract A {
// 外部函數
// ...
// 公有函數
// ...
// 內部函數
// ...
function A() public {
...
}
function() public {
...
}
// 私有函數
// ...
}
明確函數的可見性
所有的函數(包括構造函數)應該在定義的時候明確函數的可見性,例如應該使用:
function explicitlyPublic(uint val) public {
doSomething();
}
而不是
function implicitlyPublic(uint val) {
doSomething();
}
可見性應該在修飾符前面
函數的可見性應該寫在自定義的函數修飾符前面,例如:
function kill() public onlyowner {
selfdestruct(owner);
}
而不是
function kill() onlyowner public {
selfdestruct(owner);
}
區分函數和事件
為了防止函數和事件(Event)產生混淆,聲明一個事件使用大寫並加入前綴(可使用LOG)。對於函數, 始終以小寫字母開頭,構造函數除外。
// 不建議
event Transfer() {}
function transfer() {}
// 建議
event LogTransfer() {}
function transfer() external {}
常量
常量應該使用全大寫及下劃線分割大詞的方式,如:MAX_BLOCKS,TOKEN_NAME, CONTRACT_VERSION。
參考文獻
Solidity style-guide
深入淺出區塊鏈 - 系統學習區塊鏈,打造最好的區塊鏈技術博客。
智能合約最佳實踐 之 Solidity 編碼規範