Readable Code 淺顯易懂的程式

如何寫一個大家都看得懂的程式呢? 最近讀了 「The Art of Readable Code 」與「Clean Code A Handbook of Agile Software Craftsmanshi」這本書，將書中提到的，整合我平常寫 Code 的習慣，記錄下程式的規範。

Easy to Read, 如何讓整體的 Code 容易閱讀

• 複雜的 Function, method 請增加註解，但是注意註解不要影響程式的閱讀
• 適當的空白，空行。
• 不要過度使用文字的縮寫，如果不確定縮寫是否其他人看得懂，就寧願用很長的英文單字，也不要用沒有人看得懂的縮寫。
• 一個 function 的行數不要太多，大約 「 50 行」上限，並且保持 function 簡單容易閱讀。
• 不要用 小寫 L , 大小寫 O, o 開頭的字母
• 使用 IDE 摺疊功能，將 function 摺起來縮成一行，如 vim 內建就有 folder 的功能。

寫註解的時候要小心，透過修改變數 or function 命名來達到容易閱讀的方式為最佳，若不是萬不得以，不要寫註解。

程式排版

程式的排版非常的重要，一個好的排版，讀者才能順暢的看懂程式。

條列式

條列式的排版，比較適合大部分人的閱讀方式，舉個例好，下面這個程式就是沒有經過排版，程式碼的變數指定呈現鉅齒狀，不容易閱讀。

$nickname = $person['nickname'];
$age = $erson['age'];
$name = $person['name'];
$address = $person['zipCode'] . $person['address'];

上面那段程式你是否有注意到 第二行的變數 erson 打錯字了，接下來我們來幫程式碼好好的排版。

$nickname = $person['nickname'];
$age      = $erson['age'];
$name     = $person['name'];
$address  = $person['zipCode'] . $person['address'];

經過排版後，第二行的錯字就可以很容易的被發現，因為程式碼的可讀性變高。

程式碼區塊

一個 function 的程式碼行數大約會在 10 ~ 50 行之間，讀懂 50 行程式碼也不算是一個簡單的事，如果我們將程式碼分成多個區塊，再對每一個區塊寫下一行簡短的註解，這樣讀程式碼就更容易了，區塊註解還有另一個功能，一般人沒辦法記住每一個區塊的程式碼邏輯，而註解能提醒讀者每個段落的內容，例如下面這個例子。

function request($url, $params, $header) 
{
  // Handle http request.
  if (preg_match(/\?/, $url)) {
    $url .= "&";
  } else {
    $url .= "?";
  }
  foreach ($params as $key => $val) {
    $url .= $key . "=" . $val;
  }
 
  // Handle Curl
  $tuCurl = curl_init(); 
  curl_setopt($tuCurl, CURLOPT_URL, "https://example.com/xx/"); 
  curl_setopt($tuCurl, CURLOPT_PORT , 443); 
  $tuData = curl_exec($tuCurl); 
 
  //Handle response
  $response = json_decode($tuData, true);
  return $response;
}

tmp 暫存的變數

var tmp = "file_";
for (var i = 0; i , 20; i++)  {
   tmp += i;
}
var file = tmp + ".txt";

• tmp_file
• tmp_username

暫存的變數命名

若是真的有些變數無法命名，那就用一般的變數方式來命名。

• tmp : 不知道如何命名的暫存變數，都用 tmp
• retval : return value，用途回傳值
• it : iterator ， 用在 for each 的每一個 item。

明確的變數命名

• runLocal --> useLocalDatabase
• disallowMethod --> disallowCopyAndPaste
• id = "2" , encodeId = "abefcbad****"
• size -->sizeMB
• time --> timeMS (Million Second)
• length --> lenBytes ,
• mb_strlen('','', 'UTF8') lenUTF8 ，當使用 UTF8 編碼來計算文字長度，一個中文字代表長度 1 ，一個英文字也代表長度 1
• maxChars : 最大容納的字元
• maxBytes : 最大 byte 數
• maxMultipleBytes : 最多中文數
• MAX_ITEMS_IN_BOX : 這個 box 的最大值

停止事件 , stop , pause, kill

• stop, start : 停止某一個行為，並可以使用 start 重新啟動一個全新的事件。
• pause, resume : 暫停某個行為，但是可以重新恢復，繼續先前的進度。
• kill : 強迫結束，不管是否會造成任何問題。

常用的縮寫單字

除了一些常用的，大家都懂的縮寫單字之外，盡量不要使用其他的縮寫單字，使用過多的縮寫單字，會造成程式閱讀的困難，再加上每個人英文程度不同，很容易造成誤解。

• str : string
• len : length
• eval : evaluation
• doc : document
• db : database
• util : utility
• ms : million second
• us : 微秒
• addr : address
• 來源 src ，目的地 dest

不好的範例

• backendManager => BEManager , BEManager 很難看得懂
• googleTranslator => GT
• color: clr

不要使用反向意思, un , dis, anti

• 例如我曾經碰過有人命名 unFold = true ，代表打開這個節點 , unFold = false 代表關閉節點 ，那 if (empty($unFold)) 到底是開還是關呢?
• use_encode , disable_encode

is, has, can, should , use

• isAdmin = true ，代表 User 是 Admin
• hasOrder = false ，代表這個 User 有訂單，不好的寫法是使用 notEmpty 這種反意。
• useMysql = true

Front-End 相關

• nodeName: 代表 div, span, body 等等。
• elm: element 的縮寫 ，代表 html 中某一個 node 的物件。

與他人合作

如果你是單兵作戰部隊，那你想怎麼寫 code 都不會有人理你，但是當你在一個團隊中時，你寫的程式，未來將會有很多人幫你維護，修改，解 Bug ，所以寫 Code 的時候，必須想到接手的人是否能夠快速的理解你寫程式。

變數的名稱要能發音，請使用念得出來的英文字母來當變數，當我們必須使用縮寫或是自創文字，這時盡量組成一個容易發音的單字，這樣與其他工程師討論時會比較容易，或是對新人教學時也會方便很多。

重要變數的數值必須要可以被搜尋到 ，例如我定義訂單的 status = 5 時，代表這是一筆成功的訂單，並且我要更新訂單資訊 , 我可以先定義一個常數變數 STATUS_OPEN = 5 , 這樣當我想查詢 status = 5 ，程式會執行那幾行 Code 時，這時我可以搜尋 STATUS_OPEN 這個字母，而不是搜尋 「5」這個數字 (你如果搜尋 5 的話，會搜尋到相當多的垃圾)。

var STATUS_CLOSE = 4;
var STATUS_OPEN = 5;
if (status == STATUS_SUCCESS) {
      updateOrder();
}

其他相關

• begin , end => first, last ， end 代表最後一個，但是沒辦法說明是否包含最後一個，

if (aaaaaaaa == "bbbbbbbbb" &&
    ccccccc  == "adddddddd" 
   ) {
}

• 物件分類，類似的功能的 function 放在一起。

class xx
{
   //fetch data
   function fetchJS(){}
   function fetchCSS(){}
   //save 
   function saveJS(){}
   function saveCSS(){}
   //convert encoding
   function convertToUTF8(){}
   function convertToBig5(){}
}

Function 的開頭與結尾括號

不管那一種語言， function 都會有一個開頭與結尾大括號 "{}" ，建議括號都能自已獨立一行，例如下面這個範例，好處是，當我們使用 IDE 將 function 做折疊功能時，function 名稱與參數最好不要被折疊，這樣程式碼可讀性比較高。

// 折疊前
void fetchUser(int userId, bool isAdmin)
{
     ret = db.query("xxx");
 
}  
 
// 好讀的折疊結果
void fetchUser(int userId, bool isAdmin)
+--  4 lines: {--------------------------------------------------------------------------------------------------------------
 
// 括號不斷行的話，程式碼會折疊成一行
+--  4 lines: void fetchUser(int userId, bool isAdmin) {------------------