| 编辑推荐: |
| 本文来自于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');
|
|
