iCMS

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

iCMS http://www.hlike.cn 2017-12-12 15:01 出处:网络 编辑:@iCMS
好喜欢是一个专门转载优质博客文章的地方

在本文中,作者从注释,缩进,代码分组,命名方式等方面,介绍了10个提高代码可读性的技巧,供读者学习和借鉴。 


以下为译文:


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


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


1. 注释和文档


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


考虑一下这个例子: 


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

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


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


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

 在这些示例中,使用的注释(或文档)的类型基于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 Style


function foo()

{ //placed on the next line

   if($maybe) { // placed on the same line

       do_it_now();

       again();

   } else {

      abort_mission();

   }

   finalize();

}


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


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


3 避免冗余的注释


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


// get the country code

$country_code = get_country_code($_SERVER['REMOTE_ADDR']);

// if country code is US

if ($country_code == 'US'){

// display the form input for state

echo form_input_state();

}


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


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


// display state selection for US users

$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中,大多数代码都使用camelCase方式来命名,而在PHP中,大部分代码都使用underscores命名方式。


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


classFoo_Bar{

publicfunctionsomeDummyMethod(){

}


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


6. DRY Principle(干燥原理)


DRY意思是不要重复,即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. 限制行的长度


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


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

 


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


//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,status    

 FROM users  

 LEFT JOIN user_posts

 USING(users.id,user_posts.user_id)    

 WHERE post_id = '123'";


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


9. 文件和文件夹结构


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


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


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


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

 


10. 一致的临时命名


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


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


// $i for loop countersfor

($i= 0; $i


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


0

精彩评论

暂无评论...
验证码 换一张
取 消