编写超级可读代码的15个最佳实践(1)

编写超级可读代码的15个最佳实践(1)

代码可读性是一个计算机编程世界的普遍主题。它是我们作为开发者第一件学习的事情。这篇文章将阐述编写可读性代码十五个最重要的最佳实践。

 

1. 注释和文档

集成开发环境IDE在过去的短短几年里走过了很长的路。它使得注释代码比以前更加有用。依照特定标准书写的注释允许IDE和其他工具通过不同的方式来使用它们。

考虑如下示例：

 

我在函数定义中添加的注释可以在调用它的地方看到，即便是在其他文件中。

这里是我另外一个从第三方库中调用函数的例子：

 

在这些特殊的例子中，使用的注释(或者文档)类型基于PHPDoc，IDE是Aptana。

2 . 一致的排版

我假定你已经知道了你必须要缩进你的代码。然而，保持排版样式一致仍然是一个好主意。

这里有不止一种方式来进行代码排版。

第一种：

function foo() {  
    if ($maybe) {  
        do_it_now();  
        again();  
    } else {  
        abort_mission();  
    }  
    finalize();  
} 

第二种：

function foo()  
{  
    if ($maybe)  
    {  
        do_it_now();  
        again();  
    }  
    else 
    {  
        abort_mission();  
    }  
    finalize();  
} 

第三种：

function foo()  
{   if ($maybe)  
    {   do_it_now();  
        again();  
    }  
    else 
    {   abort_mission();  
    }  
    finalize();  
} 

我曾经使用第二种样式但是最近换为第一种。但是这仅仅只代表了一种偏爱。这里并没有每个人必须要遵守的“最好的”样式。事实上，最佳的样式，就是一致的样式。如果你是一个小组的一部分或者你在为一个项目贡献代码，你必须依照这个项目之前使用的样式。

排版的样式总不是完全和另外一个不同。有时，它们混合了多种不同的规则。例如，按照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来缩进。

这里http://en.wikipedia.org/wiki/Indent_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有些时候在遵守命名一致性方面有很大问题：

strops()和str_split()

imagetypes()和image_type_to_extension()

首先，这些命名必须有单词的分界线。有两种流行的选择：

骆驼命名法：除了第一个单词外，每个单词的第一个字符大写。

下划线命名法: 单词间采用下划线，例如mysql_real_escape_string()。

像我之前提到的一样，采用不同的命名选择会创建和排版样式类似的情形。如果一个已有的项目遵照一个确定的习惯，你必须遵守它。同时，某些语言平台倾向于使用特定的命名规则。例如Java里，大多数代码使用骆驼命名法;在PHP里大多采用下划线命名法。

它们也可以混用。一些开发者喜欢在程序函数和类名上使用下划线命名，但是在类方法名上使用骆驼命名。

class Foo_Bar {  
    public function someDummyMethod() {  
    }  
}  
function procedural_function_name() {  
} 

所以，没有明显的“最好的”样式，只需要保持一致。