您可以捐助,支持我们的公益事业。

1元 10元 50元





认证码:  验证码,看不清楚?请点击刷新验证码 必填



  求知 文章 文库 Lib 视频 iPerson 课程 认证 咨询 工具 讲座 Model Center   Code  
会员   
   
 
     
   
 订阅
  捐助
提升代码可读性的10个技巧
 
   次浏览      
 2018-1-8 
 
编辑推荐:
本文来自于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');
   
次浏览       
相关文章

深度解析:清理烂代码
如何编写出拥抱变化的代码
重构-使代码更简洁优美
团队项目开发"编码规范"系列文章
相关文档

重构-改善既有代码的设计
软件重构v2
代码整洁之道
高质量编程规范
相关课程

基于HTML5客户端、Web端的应用开发
HTML 5+CSS 开发
嵌入式C高质量编程
C++高级编程