智能合約最佳實踐 之 Solidity 編碼規範

本文首發於深刻淺出區塊鏈社區 原文連接:智能合約最佳實踐 之 Solidity 編碼規範原文已更新，請讀者前往原文閱讀

每一門語言都有其相應的編碼規範， 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 {
    ...
}

函數編寫規範

函數的順序

在編寫函數的時候，應該讓你們容易找到構造函數，回退函數，官方推薦的的函數順序是：

1. 構造函數
2. 回退函數 (若是有)
3. 外部函數（external）
4. 公有函數(public)
5. 內部函數(internal)
6. 私有函數（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 目前咱們也在招募課程體驗師，能夠點擊連接瞭解。

參考文獻

Solidity style-guide

☛ 深刻淺出區塊鏈 - 系統學習區塊鏈，打造最好的區塊鏈技術博客。

☛ 個人知識星球爲各位解答區塊鏈技術問題，歡迎加入討論。

☛ 關注公衆號「深刻淺出區塊鏈技術」第一時間獲取區塊鏈技術信息。