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

如果你的代码很容易阅读，这也会帮助你调试自己的程序，让工作变得更容易。 

代码可读性是计算机编程领域的一个普遍课题，这也是作为开发人员首先要学习的东西。本文将详细介绍几个编写可读代码的最佳实践。 

1 注释和文档  

IDE(集成开发环境)在过去的几年里取得了很大的提升，也让你的代码比以前更容易进行注释了。注释会遵循一定的标准，这就允许IDE和其他工具以不同的方式来使用它们。 
考虑一下这个例子: 

在函数定义中添加的注释可以在使用该函数时进行查看，即使是在其他文件中使用该函数也同样可以查看注释。

下面是另一个例子，从第三方库调用函数: 

在这些示例中，使用的注释(或文档)的类型基于 PHPDoc ，而IDE则是基于 Aptana 。 

2 一致的缩进  

你可能已经知道需要对代码进行缩进，然而，同样值得注意的是，保持缩进样式一致也是很重要的。 
缩进方式不止一种，下面是两个比较常见的例子。 

方式1: 

代码 

1. function foo() {  
2.     if($maybe){  
3.         do_it_now();  
4.         again();  
5.     } else{  
6.         abort_mission();  
7.     }  
8.     finalize();  
9. }  

方式2: 

代码 

1. function foo(){    
2. if($maybe) {    
3.  do_it_now();  
4.         again();  
5.     }else{    
6.  abort_mission();  
7.     }  
8.     finalize();  
9. }  

我曾经使用方式2来编写代码，但最近切换到方式1。这只是一个偏好的问题，没有一种风格是“最好”的，不需要每个人都来遵循。实际上，最好的风格是一致的风格。如果你是团队的成员，或者你正在为一个项目编写代码，那么你应该遵循该项目中正在使用的样式。 

当然，缩进样式并不总是完全不同，有时，它们也会混合不同的规则。例如，在 PEAR编码标准 中，大括号“{”会与 控制结构 保持一致；但是，它们也会被放在 函数定义 后的下一行。 

PEAR Style  

代码 

1. function foo()  
2. { //placed on the next line  
3.     if($maybe) { // placed on the same line  
4.         do_it_now();  
5.         again();  
6.     } else {  
7.        abort_mission();  
8.     }  
9.     finalize();  
10. }  

另外，请注意，这里使用的是四个空格，而不是使用tab键进行缩进。 

这是 一篇维基百科的文章，有不同缩进风格的样式。 

3 避免冗余的注释  

对你的代码进行注释是很棒的行为，然而，它可能是过量的，或者是冗余的。来看这个例子: 

代码 

1. // get the country code  
2. $country_code = get_country_code($_SERVER['REMOTE_ADDR']);  
3. // if country code is US  
4. if ($country_code == 'US'){  
5. // display the form input for state  
6. echo form_input_state();  
7. }  

当内容很显而易见的时候，进行重复的注释是很没有效率的。 

如果你必须对该代码进行注释，那你可以简单地将其合并到一行中: 

代码 

1. // display state selection for US users  
2. $country_code = get_country_code($_SERVER['REMOTE_ADDR']);  
3. if ($country_code == 'US'){  
4. echo form_input_state();  
5. }  

4 代码分组  

通常情况下，某些任务需要几行代码，那么把这些任务放在单独的代码块中是一个好主意，这会让它们之间有一些空间。 

这里有一个简化的例子: 

代码 

1. // get list of forums  
2. $forums = array();  
3. $r = mysql_query("SELECT id, name, description FROM forums");  
4. while ($d = mysql_fetch_assoc($r)){  
5. $forums[] = $d;  
6. }  
7. // load the templates  
8. load_template('header');  
9. load_template('forum_list', $forums);  
10. load_template('footer');  

在每个代码块的开头添加注释，视觉上看起来就是分离的代码块了。 

5 一致的命名方案  

PHP有时会犯不遵循一致命名方案的错误： 

代码 

1. strpos() vs. str_split()  
2. imagetypes() vs. image_type_to_extension()  

首先，命名应该有单词边界。有两种比较流行的选择: 

引用

camelCase(骆驼拼写法)：除了第一个单词,每个单词的第一个字母都大写。 
underscores(下划线)：在单词之间加下划线，例如:mysql_real_escape_string()。

类似于前面提到的缩进方式，命名方式也会有不同的选择。如果现有的项目遵循一定的方案，那么你应该使用它。此外，一些语言倾向于使用一种命名方案。例如，在Java中，大多数代码都使用camelCase方式来命名，而在PHP中，大部分代码都使用underscores命名方式。 

当然这些方式也可以混合，一些开发人员倾向于使用underscores方式来处理过程函数和类名，但却使用camelCase方式来对类方法命名: 

代码 

1. classFoo_Bar{  
2. publicfunctionsomeDummyMethod(){  
3. }  

因此，没有所谓的“最佳”风格，仅仅是需要一致的风格。 

6 DRY Principle（干燥原理）  

DRY意思是不要重复，即DIE: Duplication is Evil.（复制是邪恶的） 
原则 如下: 
“每一条知识都必须在一个系统中有一个单一的、明确的、权威的表示。”  

大多数应用程序(或一般计算机)的目的是使重复的任务自动化，所以这项原则应该在所有代码中体现出来，甚至是web应用程序。同样的代码不应该一次又一次地重复。 

例如，大多数web应用程序由许多页面组成，很有可能这些页面包含公共元素，就比如页眉和页脚。然而，将这些页眉和页脚粘贴到每个页面并不是一个好方法。下面是Jeffrey Way解释如何在CodeIgniter中创建模板。 

代码 

1. $this->load->view('includes/header');     
2. $this->load->view($main_content);     
3. $this->load->view('includes/footer');  

7 避免嵌套太深  

嵌套过多会使代码更难读取和跟踪。 

代码 

1. functiondo_stuff(){  
2. // ...  
3. if (is_writable($folder)){  
4.     if ($fp = fopen($file_path, 'w')){  
5.         if ($stuff = get_some_stuff()){  
6.             if (fwrite($fp, $stuff)){  
7. // ...  
8.    }  
9.       else  
10.    {  
11.     returnfalse;  
12.    }  
13.   }  
14.   else  
15. {  

为了便于阅读，通常可以修改代码以减少嵌套级别: 

代码 

1. functiondo_stuff(){  
2. // ...  
3. if (!is_writable($folder)){  
4. returnfalse;  
5. }  
6. if (!$fp = fopen($file_path, 'w')){  
7. returnfalse;  
8. }  
9. if (!$stuff = get_some_stuff()){  
10. returnfalse;  
11. }  
12. if (fwrite($fp, $stuff)){  
13. // ...  
14. }  
15.   else  
16. {  
17. returnfalse;  
18. }  
19. }  

8 限制行的长度  

眼睛在阅读高而窄的文本时会更舒服，这正是报纸文章看起来是这样的原因: 

避免编写太长的代码行是一个很好的做法。 

代码 

1. //bad  
2. $my_email->set_from('test@email.com')->add_to('programming@gmail.com')->set_subject('Methods Chained')->set_body('Some long message')->send();     
3. // good  
4. $my_email     
5. ->set_from('test@email.com')      
6.   ->add_to('programming@gmail.com')      
7.   ->set_subject('Methods Chained')     
8.   ->set_body('Some long message')     
9.   ->send();     
10. // bad  
11. $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'";     
12. // good  
13. $query= "SELECT id, username, first_name, last_name, status      
14.   FROM users     
15.   LEFT JOIN user_posts   
16.   USING(users.id, user_posts.user_id)      
17.   WHERE post_id = '123'";  

而且，如果有人打算从终端窗口读取代码，比如 Vim用户 ，那么将行长度限制为大约80个字符是一个比较好的做法。 

9 文件和文件夹结构  
从技术上讲，可以在一个文件中编写整个应用程序的代码，但这一定是阅读和维护代码的噩梦。 

在我的第一个编程项目中，我有创建“include files”的想法，然而还没有完全构建起来。我创建了一个“inc”文件夹，其中有两个文件db.php和functions.php。但随着应用程序的增加，函数文件也变得非常庞大，越来越不可维护。 

最好的方法之一是使用框架或模仿文件夹结构。这就是CodeIgniter的样子: 

10 一致的临时命名  

通常，变量应该是描述性的，并且包含一个或多个单词。但是，这并不一定适用于临时变量，它们可以像一个字符一样短。 

对于相同类型的临时变量，使用一致的命名是很好的做法。下面是我在代码中使用的一些例子: 

代码 

1. // $i for loop countersfor  
2. ($i= 0; $i