提升代码可读性的10个技巧

[[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 技术一起携手合作。