微信号:we21cto

介绍:21CTO(21CTO.com)是中国项级技术专家的学习与服务平台.我们为CTO、技术总监、架构师等技术专家提供高质量的资讯、问答、活动等产品,同时与企业连接,提供技术咨询、研发、运维、技术支持、培训及人才招聘等服...

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

2017-12-05 23:08 21CTO


21CTO社区导读:如果你在敏捷环境下做软件开发,代码能够具有良好的可读性是很关键的因素。本篇就是描写让代码更有阅读性的实用技巧文章。


1、注释与文档 


代码编辑器IDE(Intergrated Development Environment,集成开发环境)已经发展多年。它们能够很好的给我们提供方便的代码注释功能。以下我们谈谈在IDE和其它工具写注释的标准和方法。


我们来看如下实例:



我们在自定义函数体中的注释可以在使用该函数时被预览到,甚至可以在其它文件中进行预览。


下面是另外的例子,我们从第三方库中调用一个函数:



在这些实例中,注释的格式(文档)基于PHP Doc,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()

{ //placed on the next line

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

        do_it_now();

        again();

    } else {

       abort_mission();

    }

    finalize();

}


另外请开发者们注意,它们是用4个空格而不是用TAB键进行缩进。因为不同的编辑器对TAB的定义有所不同。在维基百科上有一篇文章,地址是 https://en.wikipedia.org/wiki/Indentation_style,它给我们展示了不同缩进样式的代码。



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()与str_split()


imagetypes与image_type_to_extension()


首先,这个名字应该有单词边界。下面是两个流行的写法:


1、camelCase


驼峰风格,即每个单词的首字母为大写,有时第一个单词除外。如:


TrimStrings


2、下划线命名


如:mysql_real_escape_string()


如前所述,和创建不同缩进样式一样,我们使用命名方案也要强力遵循标准。此外,一些语言平台也倾向不同的命名方案。例如在Java中,大多数的编码使用camelCase驼峰风格。而在PHP的项目中,大多数开发使用下划线风格。


这些也可以混合使用。有的开发者喜欢用下划线风格编写过程函数和类的名称,使用camelCase风格给类中的方法来命名。如下例 :


class Foo_Bar{

    publicf unction someDummyMethod(){

   

    }

}


值得再提的是,没有“最好”的风格,只有一致的风格。



6、干燥原则


干燥原则的英文是DRY Principle。DRY表示不要重复你自己,亦可以理解为DIE,重复是邪恶的。


此原则规定如下:


“每一段知识在一个系统中都须是单一的,明确的,权威的表现”。

大多数的应用程序(或通用的计算机系统)之目的都是自动执行重复的任务。此原则应该保持在所有的代码中,甚至是Web应用程序中。一段代码不应该一遍又一遍的重复出现。


比如,大多数Web应用由多个页面组成,这些页面包含很多通用的元素。比如页眉,导航条,页脚等都是。将这些组件元素粘贴到每个页面是一个很不负责的行为。这也是在前端开发中,比如VUE或React等单页面框架的优势。在PHP中,Jeffrey Way说明如何在CodeIgniter框架中使用模板:


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

$this->load->view($main_content);   

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



7、拒绝深度嵌套


使用太多嵌套语句,会使代码晦涩难懂,也会出现未知的错误。这一部分需要开发者思考 ,是不是自己思路的问题。


请看如下代码:


function do_stuff(){

// ...

if (is_writable($folder)){

    if ($fp = fopen($file_path, 'w')){

        if ($stuff = get_some_stuff()){

            if (fwrite($fp, $stuff)){

// ...

   }

      else

   {

    returnfalse;

   }

  }

  else

{



为了便于阅读,以上代码可以做一些更改以减少嵌套层数。


function do_stuff(){

// ...

if (!is_writable($folder)){

return false;

}

if (!$fp = fopen($file_path, 'w')){

return false;

}

if (!$stuff = get_some_stuff()){

return false;

}

if (fwrite($fp, $stuff)){

// ...

}

else

{

return false;

}

}



8、限制代码行长度


我们的眼睛在阅读高而窄的文字时会比较舒适,这也就是为什么报纸让人愿意看的原因:



避免写太长的代码是一个非常好的习惯。请看如下代码:


//不好的写法

$my_email->set_from('test@email.com')->add_to('programming@gmail.com')->set_subject('Methods Chained')->set_body('Some long message')->send();   


//好写法

$my_email   

->set_from('test@email.com')    

  ->add_to('programming@gmail.com')    

  ->set_subject('Methods Chained')   

  ->set_body('Some long message')   

  ->send();   


// 不好的写法

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

// 好写法

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


另外,还有不少人愿意在Linux环境的终端下读写代码,比如VIM、xEmacs用户,最好是将每行限制在80个字符左右。



9、文件与文件夹的组织


从技术角度来说,你可以把一个完整应用程序的代码写在一个文件里。但是,这将是一个阅读和维护的噩梦。


在我第一次参与开发的软件项目中,我有了“include”包含文件的想法,但我没有在远端实施。我创建了一个“inc”的文件夹,里面放两个文件:db.php和functions.php,用来连接数据库,还有自己的函数库。随着应用程序的变大,functions.php文件也变得异常庞大,越来越不好维护。


最好的方法是使用框架或者模仿它们的文件夹结果。以下是CodeIgniter的结构 :



以下是Laravel框架的结构(请看左侧树型结构)。



哪个更优雅,自己选择吧。



10、一致的临时名称


通常情况下,变量名应该是具有描述性的,包含一个或多个单词。但是,临时变量就不一定适合这种规则了,它们就像我们在学校时学习的C语言一样,使用很短的名字命名。


给具有相同角色的临时变量起一致的名字是一个好习惯。下面是我本人倾向使用的代码实例:


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


(完)


作者:Manas Sadangi

编译:小强

来源:https://dzone.com/articles/10-tips-how-to-improve-the-readability-of-your-sof


 
21CTO 更多文章 张一鸣全球思想盛筵演讲:新技术,新责任 “技术天才”李一男已出狱:曾被视为华为接班人!华中科大少年班,27岁华为副总裁,曾任百度CTO 乌镇互联网大会,马云、马化腾、李彦宏、雷军、库克说了些什么? PHP-FPM调优:使用’pm static‘最大化性能 加速优化网站的五大技巧
猜您喜欢 揭秘MIUI视频从0到千万用户的迭代 【Caffe实战与小数据深度学习】CNN的近期进展与实用技巧(下) 融数CTO王东谈从0到1打造有战斗力的全栈团队【中生代北京闭门会实录】 两个实例看互联网浪潮中初创企业和传统企业的选择 Visual Studio 2017 for Mac,有这些新特性