像其他語言一樣，開發人員可以用 PHP 編寫出各種質量級別的代碼。學習良好的編程習慣能夠提高代碼質量和效率。
根據具體的情況，一般的開發人員往往比優秀的開發人員的效率低 10%~20%。優秀的開發人員的效率更高，因為他們擁有豐富的經驗和良好的編程習慣。不良的編程習慣將會影響到效率。本文通過展示一些良好的編程習慣，幫助您成為更優秀的程序員。
這些良好的編程習慣不僅能提高效率，還能讓您編寫出在應用程序的整個生命周期中易於維護的代碼。編寫出來的代碼可能需要大量的維護；應用程序的維護是一筆很大的開支。養成良好的編程習慣能夠提高設計質量（比如模塊化），從而使代碼更加容易理解，因此維護就更加容易，同時也降低維護成本。
不良的編程習慣會造成代碼缺陷，使其難以維護和修改，並且很可能在修改時又引入其他缺陷。以下是 5 個良好的編程習慣，能夠幫助 PHP 代碼避免這些缺陷：
下一小節將詳細介紹這些習慣。
使用良好的命名
使用良好的命名是最重要的編程習慣，因為描述性強的名稱讓代碼更加容易閱讀和理解。代碼是否好理解取決於是否能在未來維護它。即便代碼不帶有註釋，如果它很容易理解，將大大方便日後的更改。這個習慣的目標是讓您編寫的代碼像書本一樣容易閱讀和理解。
不良習慣：含糊的或無意義的名稱
清單 1 中的代碼包含過短的變數名、難以辨認的縮寫詞，並且方法名不能反映該方法的功能。如果方法名給人的感覺是它應該做這件事情，而實際中它卻做另外的事情，這將帶來嚴重的問題，因為它會誤導人。
<?php function getNBDay($d) { switch($d) { case 5: case 6: case 7: return 1; default: return ($d + 1); } } $day = 5; $nextDay = getNBDay($day); echo ("Next day is: " . $nextDay . "\n"); ?> |
良好習慣：說明性強並且簡潔的名稱
清單 2 中的代碼體現了良好的編程習慣。新的方法名具有很強的說明性，反映了方法的用途。同樣，更改后的變數名也更具說明性。惟一的保持最短的變數是 $i，在本清單中，它是一個循環變數。儘管很多人不贊同使用過短的名稱，但在循環變數中使用還是可以接受的（甚至有好處），因為它明確表明了代碼的功能。
<?php define ('MONDAY', 1); define ('TUESDAY', 2); define ('WEDNESDAY', 3); define ('THURSDAY', 4); define ('FRIDAY', 5); define ('SATURDAY', 6); define ('SUNDAY', 7); /* * * @param $dayOfWeek * @return int Day of week, with 1 being Monday and so on. */ function findNextBusinessDay($dayOfWeek) { $nextBusinessDay = $dayOfWeek; switch($dayOfWeek) { case FRIDAY: case SATURDAY: case SUNDAY: $nextBusinessDay = MONDAY; break; default: $nextBusinessDay += 1; break; } return $nextBusinessDay; } $day = FRIDAY; $nextBusDay = findNextBusinessDay($day); echo ("Next day is:" . $nextBusDay . "\n"); ?> |
我們鼓勵您將大的條件拆分為一個方法，然後用能夠描述該條件的名字命名方法。這個技巧能夠提高代碼的可讀性，並且能夠將條件具體化，使之能夠被提取甚至重用。如果條件發生變化，更新方法也很容易。因為方法擁有一個有意義的名字，所以它能反映代碼的用途，讓代碼更容易閱讀。
  |
分成更小的部分
專心解決一個問題之後再繼續編程，這樣會讓您更輕鬆。在解決一個緊急的問題時，如果繼續編程，會使函數越來越長。從長遠來說，這並不是一個問題，但您要記得回過頭來將它重構為更小的部分。
重構是個不錯的主意，但您應該養成編寫更短、功能更集中的代碼。短的方法能夠在一個窗口中一次看完，並且容易理解。如果方法過長，不能在一個窗口中一次看完，那麼它就變得不容易理解，因為您不能快速地從頭到尾了解它的整個思路。
構建方法時，您應該養成這樣的習慣，讓每個方法只完成一件事情。這個習慣很好，因為：首先，如果方法只完成一件事情，那麼它就更容易被重用；其次，這樣的方法容易測試；第三，這樣的方法便於理解和更改。
不良習慣：過長的方法（完成很多件事情）
清單 3 展示了一個很長的函數，其中存在很多問題。它完成很多件事情，因此不夠緊湊。它也不便於閱讀、調試和測試。它要做的事情包括遍歷一個文件、構建一個列表、為每個對象賦值、執行計算等等。
<?php function writeRssFeed($user) { // Get the DB connection information // look up the user's preferences... $link = mysql_connect('mysql_host', 'mysql_user', 'mysql_password') OR die(mysql_error()); // Query $perfsQuery = sprintf("SELECT max_stories FROM user_perfs WHERE user= '%s'", mysql_real_escape_string($user)); $result = mysql_query($query, $link); $max_stories = 25; // default it to 25; if ($row = mysql_fetch_assoc($result)) { $max_stories = $row['max_stories']; } // go get my data $perfsQuery = sprintf("SELECT * FROM stories WHERE post_date = '%s'", mysql_real_escape_string()); $result = mysql_query($query, $link); $feed = "<rss version=\"2.0\">" . "<channel>" . "<title>My Great Feed</title>" . "<link>http://www.example.com/feed.xml</link>" . "<description>The best feed in the world</description>" . "<language>en-us</language>" . "<pubDate>Tue, 20 Oct 2008 10:00:00 GMT</pubDate>" . "<lastBuildDate>Tue, 20 Oct 2008 10:00:00 GMT</lastBuildDate>" . "<docs>http://www.example.com/rss</docs>" . "<generator>MyFeed Generator</generator>" . "<managingEditor>editor@example.com</managingEditor>" . "<webMaster>webmaster@example.com</webMaster>" . "<ttl>5</ttl>"; // build the feed... while ($row = mysql_fetch_assoc($result)) { $title = $row['title']; $link = $row['link']; $description = $row['description']; $date = $row['date']; $guid = $row['guid']; $feed .= "<item>"; $feed .= "<title>" . $title . "</title>"; $feed .= "<link>" . $link . "</link>"; $feed .= "<description> " . $description . "</description>"; $feed .= "<pubDate>" . $date . "</pubDate>"; $feed .= "<guid>" . $guid . "</guid>"; $feed .= "</item>"; } $feed .= "</rss"; // write the feed out to the server... echo($feed); } ?> |
如果多編寫幾個這樣的方法，維護就成了真正的難題了。
良好習慣：易管理、功能專一的方法
清單 4 將原來的方法改寫為更加緊湊、易讀的方法。在這個示例中，將一個很長的方法分解為幾個短方法，並且讓每個短方法負責一件事情。這樣的代碼對將來的重用和測試都是大有裨益的。
<?php function createRssHeader() { return "<rss version=\"2.0\">" . "<channel>" . "<title>My Great Feed</title>" . "<link>http://www.example.com/feed.xml</link>" . "<description>The best feed in the world</description>" . "<language>en-us</language>" . "<pubDate>Tue, 20 Oct 2008 10:00:00 GMT</pubDate>" . "<lastBuildDate>Tue, 20 Oct 2008 10:00:00 GMT</lastBuildDate>" . "<docs>http://www.example.com/rss</docs>" . "<generator>MyFeed Generator</generator>" . "<managingEditor>editor@example.com</managingEditor>" . "<webMaster>webmaster@example.com</webMaster>" . "<ttl>5</ttl>"; } function createRssFooter() { return "</channel></rss>"; } function createRssItem($title, $link, $desc, $date, $guid) { $item .= "<item>"; $item .= "<title>" . $title . "</title>"; $item .= "<link>" . $link . "</link>"; $item .= "<description> " . $description . "</description>"; $item .= "<pubDate>" . $date . "</pubDate>"; $item .= "<guid>" . $guid . "</guid>"; $item .= "</item>"; return $item; } function getUserMaxStories($db_link, $default) { $perfsQuery = sprintf("SELECT max_stories FROM user_perfs WHERE user= '%s'", mysql_real_escape_string($user)); $result = mysql_query($perfsQuery, $db_link); $max_stories = $default; if ($row = mysql_fetch_assoc($result)) { $max_stories = $row['max_stories']; } return $max_stories; } function writeRssFeed($user) { // Get the DB connection information $settings = parse_ini_file("rss_server.ini"); // look up the user's preferences... $link = mysql_connect($settings['db_host'], $settings['user'], $settings['password']) OR die(mysql_error()); $max_stories = getUserMaxStories($link, 25); // go get my data $newsQuery = sprintf("SELECT * FROM stories WHERE post_date = '%s'", mysql_real_escape_string(time())); $result = mysql_query($newsQuery, $link); $feed = createRssHeader(); $i = 0; // build the feed... while ($row = mysql_fetch_assoc($result)) { if ($i < $max_stories) { $title = $row['title']; $link = $row['link']; $description = $row['description']; $date = $row['date']; $guid = $row['guid']; $feed .= createRssItem($title, $link, $description, $date, $guid); $i++; } else { break; } } mysql_close($link); $feed .= createRssFooter(); // write the feed out to the server... echo($feed); } ?> |
將長方法拆分為短方法也是有限制的，過度拆分將適得其反。因此，不要濫用這個良好的習慣。將代碼分成大量的片段就像沒有拆分長代碼一樣，都會造成閱讀困難。
|
為代碼添加註釋
要為代碼添加良好的註釋有時似乎和編寫代碼一樣難。要了解應該為哪些內容添加註釋並不容易，因為我們常常傾向於註釋代碼當前做的事情。註釋代碼的目的是不錯的主意。在函數的不是很明顯的頭部代碼塊中，告訴讀者方法的輸入和輸出，以及方法的最初目標。
註釋代碼當前做什麼是很常見的，但這是不必要的。如果代碼很複雜，不得不註釋它當前在做什麼，這將暗示您應該重寫代碼，讓它更容易理解。學會使用良好的名稱和更短的方法，在不提供註釋說明其用途的情況下提高代碼的可讀性。
不良習慣：函數註釋過多或不足
清單 5 中的註釋僅告訴讀者代碼在做什麼 — 它正在通過一個循環進行迭代或添加一個數字。但它忽略了它為什麼 做當前的工作。這使維護該代碼的人員不知道是否可以安全地更改代碼（不引入新缺陷）。
<?php class ResultMessage { private $severity; private $message; public function __construct($sev, $msg) { $this->severity = $sev; $this->message = $msg; } public function getSeverity() { return $this->severity; } public function setSeverity($severity) { $this->severity = $severity; } public function getMessage() { return $this->message; } public function setMessage($msg) { $this->message = $msg; } } function cntMsgs($messages) { $n = 0; /* iterate through the messages... */ foreach($messages as $m) { if ($m->getSeverity() == 'Error') { $n++; // add one to the result; } } return $n; } $messages = array(new ResultMessage("Error", "This is an error!"), new ResultMessage("Warning", "This is a warning!"), new ResultMessage("Error", "This is another error!")); $errs = cntMsgs($messages); echo("There are " . $errs . " errors in the result.\n"); ?> |
良好習慣：帶註釋的函數和類
清單 6 中的註釋告訴讀者類和方法的目的。該註釋解釋了為什麼代碼在做當前的工作，這對未來維護代碼十分有用。可能需要根據條件變更而修改代碼，如果能夠輕鬆了解代碼的目的，則修改起來很容易。
<?php /** * The ResultMessage class holds a message that can be returned * as a result of a process. The message has a severity and * message. * * @author nagood * */ class ResultMessage { private $severity; private $message; /** * Constructor for the ResultMessage that allows you to assign * severity and message. * @param $sev See {@link getSeverity()} * @param $msg * @return unknown_type */ public function __construct($sev, $msg) { $this->severity = $sev; $this->message = $msg; } /** * Returns the severity of the message. Should be one * "Information", "Warning", or "Error". * @return string Message severity */ public function getSeverity() { return $this->severity; } /** * Sets the severity of the message * @param $severity * @return void */ public function setSeverity($severity) { $this->severity = $severity; } public function getMessage() { return $this->message; } public function setMessage($msg) { $this->message = $msg; } } /* * Counts the messages with the given severity in the array * of messages. * * @param $messages An array of ResultMessage * @return int Count of messages with a severity of "Error" */ function countErrors($messages) { $matchingCount = 0; foreach($messages as $m) { if ($m->getSeverity() == "Error") { $matchingCount++; } } return $matchingCount; } $messages = array(new ResultMessage("Error", "This is an error!"), new ResultMessage("Warning", "This is a warning!"), new ResultMessage("Error", "This is another error!")); $errs = countErrors($messages); echo("There are " . $errs . " errors in the result.\n"); ?> |
|
處理錯誤
根據大眾的經驗，如果要編寫健壯的應用程序，錯誤處理要遵循 80/20 規則：80% 的代碼用於處理異常和驗證，20% 的代碼用於完成實際工作。在編寫程序的基本邏輯（happy-path）代碼 時經常這樣做。這意味著編寫適用於基本條件的代碼，即所有的數據都是可用的，所有的條件符合預期。這樣的代碼在應用程序的生命周期中可能很脆弱。另一個極端是，甚至需要花大量時間為從未遇到過的條件編寫代碼。
這一習慣要求您編寫足夠的錯誤處理代碼，而不是編寫對付所有錯誤的代碼，以致代碼遲遲不能完成。
不良習慣：根本沒有錯誤處理代碼
清單 7 中的代碼演示了兩個不良習慣。第一，沒有檢查輸入的參數，即使知道處於某些狀態的參數會造成方法出現異常。第二，代碼調用一個可能拋出異常的方法，但沒有處理該異常。當發生問題時，代碼的作者或維護該代碼的人員只能猜測問題的根源。
<?php // Get the actual name of the function convertDayOfWeekToName($day) { $dayNames = array( "Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"); return $dayNames[$day]; } echo("The name of the 0 day is: " . convertDayOfWeekToName(0) . "\n"); echo("The name of the 10 day is: " . convertDayOfWeekToName(10) . "\n"); echo("The name of the 'orange' day is: " . convertDayOfWeekToName('orange') . "\n"); ?> |
良好習慣：處理異常
清單 8 展示了以有意義的方式拋出和處理異常。額外的錯誤處理不僅使代碼更加健壯，它還提高代碼的可讀性，使代碼更容易理解。處理異常的方式很好地說明了原作者在編寫方法時的意圖。
<?php /** * This is the exception thrown if the day of the week is invalid. * @author nagood * */ class InvalidDayOfWeekException extends Exception { } class InvalidDayFormatException extends Exception { } /** * Gets the name of the day given the day in the week. Will * return an error if the value supplied is out of range. * * @param $day * @return unknown_type */ function convertDayOfWeekToName($day) { if (! is_numeric($day)) { throw new InvalidDayFormatException('The value \'' . $day . '\' is an ' . 'invalid format for a day of week.'); } if (($day > 6) || ($day < 0)) { throw new InvalidDayOfWeekException('The day number \'' . $day . '\' is an ' . 'invalid day of the week. Expecting 0-6.'); } $dayNames = array( "Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"); return $dayNames[$day]; } echo("The name of the 0 day is: " . convertDayOfWeekToName(0) . "\n"); try { echo("The name of the 10 day is: " . convertDayOfWeekToName(10) . "\n"); } catch (InvalidDayOfWeekException $e) { echo ("Encountered error while trying to convert value: " . $e->getMessage() . "\n"); } try { echo("The name of the 'orange' day is: " . convertDayOfWeekToName('orange') . "\n"); } catch (InvalidDayFormatException $e) { echo ("Encountered error while trying to convert value: " . $e->getMessage() . "\n"); } ?> |
雖然檢查參數是一種確認 — 如果您要求參數處於某種狀態，這將對使用方法的人很有幫助 — 但是您應該檢查它們並拋出有意義的異常：
|
切忌使用複製粘貼
您可以從其他地方將代碼複製粘貼到自己的代碼編輯器，但這樣做有利也有弊。好的一面是，從一個示例或模板中複製代碼能夠避免很多錯誤。不好的一面是，這容易帶來大量的類似編程方式。
一定要注意，不要將代碼從應用程序的一部分複製粘貼到另一部分。如果您採用這種方式，請停止這個不良的習慣，然後考慮將這段代碼重寫為可重用的。一般而言，將代碼放置到一個地方便於日後的維護，因為這樣只需在一個地方更改代碼。
不良習慣：類似的代碼段
清單 9 給出了幾個幾乎一樣的方法，只是其中的值不同而已。有一些工具可以幫助找到複製粘貼過來的代碼（參見 參考資料）。
<?php /** * Counts the number of messages found in the array of * ResultMessage with the getSeverity() value of "Error" * * @param $messages An array of ResultMessage * @return unknown_type */ function countErrors($messages) { $matchingCount = 0; foreach($messages as $m) { if ($m->getSeverity() == "Error") { $matchingCount++; } } return $matchingCount; } /** * Counts the number of messages found in the array of * ResultMessage with the getSeverity() value of "Warning" * * @param $messages An array of ResultMessage * @return unknown_type */ function countWarnings($messages) { $matchingCount = 0; foreach($messages as $m) { if ($m->getSeverity() == "Warning") { $matchingCount++; } } return $matchingCount; } /** * Counts the number of messages found in the array of * ResultMessage with the getSeverity() value of "Information" * * @param $messages An array of ResultMessage * @return unknown_type */ function countInformation($messages) { $matchingCount = 0; foreach($messages as $m) { if ($m->getSeverity() == "Information") { $matchingCount++; } } return $matchingCount; } $messages = array(new ResultMessage("Error", "This is an error!"), new ResultMessage("Warning", "This is a warning!"), new ResultMessage("Error", "This is another error!")); $errs = countErrors($messages); echo("There are " . $errs . " errors in the result.\n"); ?> |
良好習慣：帶參數的可重用函數
清單 10 展示了修改後的代碼，它將複製的代碼放到一個方法中。另一個方法也進行了更改，它現在將任務委託給新的方法。構建通用的方法需要花時間設計，並且這樣做使您能停下來思考，而不是本能地使用複製粘貼。但有必要進行更改時，對通用的方法投入的時間將得到回報。
<?php /* * Counts the messages with the given severity in the array * of messages. * * @param $messages An array of ResultMessage * @return int Count of messages matching $withSeverity */ function countMessages($messages, $withSeverity) { $matchingCount = 0; foreach($messages as $m) { if ($m->getSeverity() == $withSeverity) { $matchingCount++; } } return $matchingCount; } /** * Counts the number of messages found in the array of * ResultMessage with the getSeverity() value of "Error" * * @param $messages An array of ResultMessage * @return unknown_type */ function countErrors($messages) { return countMessages($messages, "Errors"); } /** * Counts the number of messages found in the array of * ResultMessage with the getSeverity() value of "Warning" * * @param $messages An array of ResultMessage * @return unknown_type */ function countWarnings($messages) { return countMessages($messages, "Warning"); } /** * Counts the number of messages found in the array of * ResultMessage with the getSeverity() value of "Warning" * * @param $messages An array of ResultMessage * @return unknown_type */ function countInformation($messages) { return countMessages($messages, "Information"); } $messages = array(new ResultMessage("Error", "This is an error!"), new ResultMessage("Warning", "This is a warning!"), new ResultMessage("Error", "This is another error!")); $errs = countErrors($messages); echo("There are " . $errs . " errors in the result.\n"); ?> |
|
結束語
如果您在編寫 PHP 代碼的過程中養成本文討論的良好習慣，您將能夠構建易讀、易理解、易維護的代碼。使用這種方式構建的易維護代碼將降低調試、修復和擴展代碼所面臨的風險。
使用良好的名稱和更短的方法能夠提高代碼的可讀性。註釋代碼的目的有利於代碼理解和擴展。適當地處理錯誤會使代碼更加健壯。最後，停止使用複製粘貼，保持代碼乾淨，提高可重用性。（責任編輯：A6）
[火星人 ] PHP 編程的 5 個良好習慣已經有497次圍觀
