[[208015]]

具有較強可讀性的代碼，能幫助你調試程序，不讓自己活得太累。

代碼可讀性是計算機編程領域中普遍存在的問題。這也是我們成為開發者首先要學習的事情之一。本文會詳細介紹在編寫強可讀性代碼時***實踐中最重要的一部分內容。

1 – 注釋和文檔

IDE(Integrated Development Environmnet，集成開發環境)在過去數年中已經存在了很長時間。使用 IDE 注釋代碼比以往容易得多。某些確切的注釋標準可以讓 IDE 和其它工具以不同的方式來完成注釋。

看個示例：

我在這里添加到函數定義前的注釋可以在使用函數的時候顯示出來，甚至在其它文件中使用這個函數也沒問題。

下面是另一個示例，關于調用一個第三方庫的函數：

在這些示例中，注釋(或文檔)的類型是基于 PHPDoc 的，使用的 IDE 是 Aptana。

2 – 保持一致的縮進

假設你已經知道代碼需要縮進。不過值得注意的是，***保持縮進樣式一致。

縮進代碼的方式很多，這里最最常見的兩種：

風格 1:

function foo() { 
    if($maybe){ 
        do_it_now(); 
        again(); 
    } else{ 
        abort_mission(); 
    } 
    finalize(); 
}  

風格 2:

function foo(){   
if($maybe) {   
 do_it_now(); 
        again(); 
    }else{   
 abort_mission(); 
    } 
    finalize(); 
}  

我以前使用的風格 #2，但最近改為 #1 了。但這個問題只是一個偏好的問題。沒有“***”的風格來讓每一個人都去遵循。實際上，***的風格就是一致的風格。如果你是團隊的一員，或者你在向某個項目貢獻代碼，你就應該遵循項目中正在使用的風格。

縮進風格間并不總是會有明顯的區別。有時候，不同的規則會產生混淆。比如，在 PEAR 編碼標準中，前大括號“{”與控制結構在同一行，但在函數定義中卻需要換行。

PEAR 風格:

function foo(){                     
// 放在下一行[譯者注：示例中明明是放在與聲明同行的，可能是作者筆誤] 
    if($maybe){      
      // 放在同一行 
        do_it_now(); 
        again(); 
    }else{ 
       abort_mission(); 
    } 
    finalize(); 
}  

另外，請注意，縮進是用的 4 個空格而不是制表符。

這里是 Wikipedia 中不同縮進風格的示例。

3 – 避免顯而易見的注釋

注釋代碼非常棒;但是，如果注釋只是簡單的重復就顯得多余了。看看這個示例：

// 獲取國家/地區代碼 
$country_code = get_country_code($_SERVER['REMOTE_ADDR']); 
// 如果國家/地區代碼是 US 
if ($country_code == 'US'){ 
// 在表單中顯示“州”輸入框 
echo form_input_state(); 
}  

如果文本是顯而易見的，真的沒必要在注釋里再寫一次。

如果你一定要在代碼里寫點注釋，可以把它們合并在一行：

// 對美國用戶顯示“州”輸入框 
$country_code = get_country_code($_SERVER['REMOTE_ADDR']); 
if ($country_code == 'US'){ 
echo form_input_state(); 
}  

4 – 代碼分組

某些任務往往不是幾句代碼就能解決的，那***把這些任務代碼分為不同的代碼段，在它們之間添加一些空行。

下面是一個簡單的示例：

// get list of forums 
$forums = array(); 
$r = mysql_query("SELECT id, name, description FROM forums"); 
 
while ($d = mysql_fetch_assoc($r)){ 
$forums[] = $d; 
} 
 
// load the templates 
load_template('header'); 
load_template('forum_list', $forums); 
load_template('footer');  

在每段代碼前添加注釋可以加強視覺分離效果。

5 – 保持一致的命名規范

PHP 本身有時候并不遵循一致的命名規范：

• strpos() vs. str_split()
• imagetypes() vs. image_type_to_extension()

首先，名字應該有單詞的邊界。下面是兩種流行的選擇：

• 駝峰風格(camelCase)：除***個單詞外每個單詞的***個字母都大寫。
• 下劃線(underscores): 在單詞間使用下劃線分隔，比如：mysql_real_escape_string()。

這一點與我前面提到使用不同縮進風格的情況相似。如果項目中已經在使用某個約定，你應該遵循它。另外，某些語言平臺往往會有一個特定的命名規范。比如在 Java 中，多數代碼使用駝峰命名風格，而多數 PHP 程序員使用下劃線命名風格。

這些網絡也可以混合使得。有些開發者喜歡對過程函數和類使用下劃線風格，但對類方法使用駝峰風格：

class Foo_Bar { 
    publicfunctionsomeDummyMethod(){ 
}  

再強調一下，沒有“***”的風格，保持一致就好。

6 – DRY 原則

DRY 代表不要重復你勞動(Don’t Repeat Yourself)。也被稱為 DIE：復制是不可接受的(Duplication is Evil)。

該原則規定：

“每個知識必須在一個系統內具有一個唯一的、明確的、權威的表示。”大多數應用程序(或通用的計算機)的目標是使重復的任務變得自動化。這個原則應該在所有的代碼中保留，包括 Web 應用程序中。同一段代碼不應該一再地被重復。

例如，大多數 Web 應用程序由許多頁面組成。這些頁面很可能包含通用的元素。標題和頁腳通常是***證明。將這些頁眉和頁腳在每個頁面中復制一份并不是一個好主意。 Jeffrey Way 在此解釋了如何在 CodeIgniter 中創建模板。

$this->load->view('includes/header');    
$this->load->view($main_content);    
$this->load->view('includes/footer');  

7 – 避免深嵌套

過多的嵌套層次會使代碼變得難以閱讀和跟蹤

functiondo_stuff(){ 
// ... 
if (is_writable($folder)){ 
    if ($fp = fopen($file_path, 'w')){ 
        if ($stuff = get_some_stuff()){ 
            if (fwrite($fp, $stuff)){ 
// ... 
   } 
      else 
   { 
    returnfalse; 
   } 
  } 
  else 
{  

為了提高可讀性，通常會通過修改代碼來減少嵌套的層級：

functiondo_stuff(){ 
// ... 
if (!is_writable($folder)){ 
returnfalse; 
} 
if (!$fp = fopen($file_path, 'w')){ 
returnfalse; 
} 
if (!$stuff = get_some_stuff()){ 
returnfalse; 
} 
if (fwrite($fp, $stuff)){ 
// ... 
} 
  else 
{ 
returnfalse; 
} 
}  

8 – 限制行長度

人眼在閱讀窄長的列式文本時感覺更舒適，這也是為什么報紙的文章都是這個樣子：

避免代碼行水平過長是一種良好的變成習慣

//bad 
$my_email->set_from('test@email.com')->add_to('programming@gmail.com')->set_subject('Methods Chained')->set_body('Some long message')->send();    
// good 
$my_email    
->set_from('test@email.com')     
  ->add_to('programming@gmail.com')     
  ->set_subject('Methods Chained')    
  ->set_body('Some long message')    
  ->send();    
// bad 
$query= "SELECT id, username, first_name, last_name, status FROM users LEFT JOIN user_posts USING(users.id, user_posts.user_id) WHERE post_id = '123'";    
// good 
$query= "SELECT id, username, first_name, last_name, status     
  FROM users    
  LEFT JOIN user_posts  
  USING(users.id, user_posts.user_id)     
  WHERE post_id = '123'";  

當然，如果有人，比如 Vim 用戶，想要在終端窗口中閱讀你的代碼，***將代碼行的長度限制在 80 個字符左右。

9 – 文件和文件夾的組織

從技術上講，你可以在單個文件中編寫整個應用程序的代碼。但是，這對閱讀和維護來說將是一個噩夢。

在我的***個編程項目中，我懂得了創建“包含文件”的作法。不過，我還沒有接觸過遠程組織。我創建了一個“inc”文件夾，其中包含兩個文件：db.php 和 functions.php。隨著應用的擴展，functions 文件也變得龐大和不可維護。

***的方法之一就是使用框架或者模擬其文件夾結構。下面是 CodeIgniter 的代碼布局：

10 – 一致的臨時變量命名

通常，變量應該是描述性的，并且包含一個或多個單詞。但是，這并不一定適用于臨時變量。它們可以短到單個字符的長度。

對于具有相同作用的臨時變量，使用一致的命名是一個很好的做法。以下是我在代碼中常用的幾個示例：

// $i for loop countersfor 
($i= 0; $i< 100; $i++) {        
  // $j for the nested loop counters     
  for($j= 0; $j< 100; $j++) {        
  } 
}    
// $ret for return variables 
functionfoo() {     
 $ret['bar'] = get_bar();     
 $ret['stuff'] = get_stuff();        
 return$ret; 
}    
// $k and $v in foreachforeach 
($some_arrayas$k=> $v) {    
}    
// $q, $r and $d for mysql 
$q= "SELECT * FROM table"; 
$r= mysql_query($q); 
while($d= mysql_fetch_assocr($r)) {   
}    
// $fp for file pointers\ 
$fp= fopen('file.txt','w');  

探索 TDM 對于敏捷、DevOps 和持續交付中速度和質量的必要性。與 CA 技術一起攜手合作。