具有較強(qiáng)可讀性的代碼，能幫助你調(diào)試程序，不讓自己活得太累。

代碼可讀性是計(jì)算機(jī)編程領(lǐng)域中普遍存在的問(wèn)題。這也是我們成為開(kāi)發(fā)者首先要學(xué)習(xí)的事情之一。本文會(huì)詳細(xì)介紹在編寫(xiě)強(qiáng)可讀性代碼時(shí)最佳實(shí)踐中最重要的一部分內(nèi)容。

1 - 注釋和文檔

IDE（Integrated Development Environmnet，集成開(kāi)發(fā)環(huán)境）在過(guò)去數(shù)年中已經(jīng)存在了很長(zhǎng)時(shí)間。使用 IDE 注釋代碼比以往容易得多。某些確切的注釋標(biāo)準(zhǔn)可以讓 IDE 和其它工具以不同的方式來(lái)完成注釋。

看個(gè)示例：

我在這里添加到函數(shù)定義前的注釋可以在使用函數(shù)的時(shí)候顯示出來(lái)，甚至在其它文件中使用這個(gè)函數(shù)也沒(méi)問(wèn)題。

下面是另一個(gè)示例，關(guān)于調(diào)用一個(gè)第三方庫(kù)的函數(shù)：

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

2 - 保持一致的縮進(jìn)

假設(shè)你已經(jīng)知道代碼需要縮進(jìn)。不過(guò)值得注意的是，最好保持縮進(jìn)樣式一致。

縮進(jìn)代碼的方式很多，這里最最常見(jiàn)的兩種：

風(fēng)格 1:

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

風(fēng)格 2:

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

我以前使用的風(fēng)格 #2，但最近改為 #1 了。但這個(gè)問(wèn)題只是一個(gè)偏好的問(wèn)題。沒(méi)有“最好”的風(fēng)格來(lái)讓每一個(gè)人都去遵循。實(shí)際上，最好的風(fēng)格就是一致的風(fēng)格。如果你是團(tuán)隊(duì)的一員，或者你在向某個(gè)項(xiàng)目貢獻(xiàn)代碼，你就應(yīng)該遵循項(xiàng)目中正在使用的風(fēng)格。

縮進(jìn)風(fēng)格間并不總是會(huì)有明顯的區(qū)別。有時(shí)候，不同的規(guī)則會(huì)產(chǎn)生混淆。比如，在?PEAR 編碼標(biāo)準(zhǔn)中，前大括號(hào)“{”與控制結(jié)構(gòu)在同一行，但在函數(shù)定義中卻需要換行。

PEAR 風(fēng)格:

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

另外，請(qǐng)注意，縮進(jìn)是用的 4 個(gè)空格而不是制表符。

這里是 Wikipedia 中不同縮進(jìn)風(fēng)格的示例。

3 - 避免顯而易見(jiàn)的注釋

注釋代碼非常棒；但是，如果注釋只是簡(jiǎn)單的重復(fù)就顯得多余了。看看這個(gè)示例：

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

如果文本是顯而易見(jiàn)的，真的沒(méi)必要在注釋里再寫(xiě)一次。

如果你一定要在代碼里寫(xiě)點(diǎn)注釋，可以把它們合并在一行：

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

4 - 代碼分組

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

下面是一個(gè)簡(jiǎn)單的示例：

// 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');

在每段代碼前添加注釋可以加強(qiáng)視覺(jué)分離效果。

5 - 保持一致的命名規(guī)范

PHP 本身有時(shí)候并不遵循一致的命名規(guī)范：

• strpos() vs. str_split()

• imagetypes() vs. image_type_to_extension()

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

• 駝峰風(fēng)格（camelCase）：除第一個(gè)單詞外每個(gè)單詞的第一個(gè)字母都大寫(xiě)。

• 下劃線（underscores）:?在單詞間使用下劃線分隔，比如：mysql_real_escape_string()。

這一點(diǎn)與我前面提到使用不同縮進(jìn)風(fēng)格的情況相似。如果項(xiàng)目中已經(jīng)在使用某個(gè)約定，你應(yīng)該遵循它。另外，某些語(yǔ)言平臺(tái)往往會(huì)有一個(gè)特定的命名規(guī)范。比如在 Java 中，多數(shù)代碼使用駝峰命名風(fēng)格，而多數(shù)?PHP 程序員使用下劃線命名風(fēng)格。

這些網(wǎng)絡(luò)也可以混合使得。有些開(kāi)發(fā)者喜歡對(duì)過(guò)程函數(shù)和類使用下劃線風(fēng)格，但對(duì)類方法使用駝峰風(fēng)格：

class Foo_Bar { ? publicfunctionsomeDummyMethod(){ ? }

再?gòu)?qiáng)調(diào)一下，沒(méi)有“最好”的風(fēng)格，保持一致就好。

6 - DRY 原則

DRY 代表不要重復(fù)你勞動(dòng)（Don't Repeat Yourself）。也被稱為 DIE：復(fù)制是不可接受的（Duplication is Evil）。

該原則規(guī)定：

“每個(gè)知識(shí)必須在一個(gè)系統(tǒng)內(nèi)具有一個(gè)唯一的、明確的、權(quán)威的表示。”

大多數(shù)應(yīng)用程序（或通用的計(jì)算機(jī)）的目標(biāo)是使重復(fù)的任務(wù)變得自動(dòng)化。這個(gè)原則應(yīng)該在所有的代碼中保留，包括 Web 應(yīng)用程序中。同一段代碼不應(yīng)該一再地被重復(fù)。

例如，大多數(shù) Web 應(yīng)用程序由許多頁(yè)面組成。這些頁(yè)面很可能包含通用的元素。標(biāo)題和頁(yè)腳通常是最佳證明。將這些頁(yè)眉和頁(yè)腳在每個(gè)頁(yè)面中復(fù)制一份并不是一個(gè)好主意。 Jeffrey Way 在此解釋了如何在 CodeIgniter 中創(chuàng)建模板。

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

7 -?避免深嵌套

過(guò)多的嵌套層次會(huì)使代碼變得難以閱讀和跟蹤

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

為了提高可讀性，通常會(huì)通過(guò)修改代碼來(lái)減少嵌套的層級(jí)：

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 -?限制行長(zhǎng)度

人眼在閱讀窄長(zhǎng)的列式文本時(shí)感覺(jué)更舒適，這也是為什么報(bào)紙的文章都是這個(gè)樣子：

避免代碼行水平過(guò)長(zhǎng)是一種良好的變成習(xí)慣

//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'";

當(dāng)然，如果有人，比如?Vim?用戶，想要在終端窗口中閱讀你的代碼，最好將代碼行的長(zhǎng)度限制在 80 個(gè)字符左右。

9 - 文件和文件夾的組織

從技術(shù)上講，你可以在單個(gè)文件中編寫(xiě)整個(gè)應(yīng)用程序的代碼。但是，這對(duì)閱讀和維護(hù)來(lái)說(shuō)將是一個(gè)噩夢(mèng)。

在我的第一個(gè)編程項(xiàng)目中，我懂得了創(chuàng)建“包含文件”的作法。不過(guò)，我還沒(méi)有接觸過(guò)遠(yuǎn)程組織。我創(chuàng)建了一個(gè)“inc”文件夾，其中包含兩個(gè)文件：db.php 和?

functions.php。隨著應(yīng)用的擴(kuò)展，functions 文件也變得龐大和不可維護(hù)。

最好的方法之一就是使用框架或者模擬其文件夾結(jié)構(gòu)。下面是?CodeIgniter 的代碼布局：

10 - 一致的臨時(shí)變量命名

通常，變量應(yīng)該是描述性的，并且包含一個(gè)或多個(gè)單詞。但是，這并不一定適用于臨時(shí)變量。它們可以短到單個(gè)字符的長(zhǎng)度。

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

// $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 對(duì)于敏捷、DevOps 和持續(xù)交付中速度和質(zhì)量的必要性。與?CA 技術(shù)一起攜手合作。?

來(lái)自：開(kāi)源中國(guó)社區(qū)

鏈接：https://www.oschina.net/translate/10-tips-how-to-improve-the-readability-of-your-sof

原文：https://dzone.com/articles/10-tips-how-to-improve-the-readability-of-your-sof

總結(jié)

以上是生活随笔為你收集整理的提升代码可读性的 10 个技巧的全部?jī)?nèi)容，希望文章能夠幫你解決所遇到的問(wèn)題。

如果覺(jué)得生活随笔網(wǎng)站內(nèi)容還不錯(cuò)，歡迎將生活随笔推薦給好友。