具有較強可讀性的代碼,代碼可讀性不是看起來好看那麼簡單。代碼追求可讀性的目的是降低他人閱讀你的代碼的難度,能幫助你調試程序,所以你的代碼要在以下三個層次上易讀:
1)文本清晰可讀
2)信息充分富集
3)邏輯容易理解
下面簡單介紹強可讀性代碼的實踐。
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('[email protected]')->add_to('[email protected]')->set_subject('Methods Chained')->set_body('Some long message')->send();
// good
$my_email
->set_from('[email protected]')
->add_to('[email protected]')
->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');