优大网

译者：蒋宇捷（转载请标明出处-http://blog.csdn.net/hfahe）

       一月两次，我们重温Nettuts历史上读者最喜欢的文章。

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

1 – 注释和文档

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

考虑如下示例：

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

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

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

2 – 一致的排版

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

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

第一种：

1. function foo()
2. {
3.     if ($maybe)
4.     {
5.         do_it_now();
6.         again();
7.     }
8.     else
9.     {
10.         abort_mission();
11.     }
12.     finalize();
13. }

1. function foo()
2. {   if ($maybe)
3.     {   do_it_now();
4.         again();
5.     }
6.     else
7.     {   abort_mission();
8.     }
9.     finalize();
10. }

1. function foo()
2. {                     // placed on the next line
3.     if ($maybe) {     // placed on the same line
4.         do_it_now();
5.         again();
6.     } else {
7.         abort_mission();
8.     }
9.     finalize();
10. }

1. // get the country code
2. $country_code = get_country_code($_SERVER[‘REMOTE_ADDR’]);
3. // if country code is US
4. if ($country_code == ‘US’) {
5.     // display the form input for state
6.     echo form_input_state();
7. }

1. // display state selection for US users
2. $country_code = get_country_code($_SERVER[‘REMOTE_ADDR’]);
3. if ($country_code == ‘US’) {
4.     echo form_input_state();
5. }

1. // get list of forums
2. $forums = array();
3. $r = mysql_query(“SELECT id, name, description FROM forums”);
4. while ($d = mysql_fetch_assoc($r)) {
5.     $forums []= $d;
6. }
7. // load the templates
8. load_template(‘header’);
9. load_template(‘forum_list’,$forums);
10. load_template(‘footer’);

1. class Foo_Bar {
2.     public function someDummyMethod() {
3.     }
4. }
5. function procedural_function_name() {
6. }

1. $this->load->view(‘includes/header’);
2. $this->load->view($main_content);
3. $this->load->view(‘includes/footer’);

1. function do_stuff() {
2. // …
3.     if (is_writable($folder)) {
4.         if ($fp = fopen($file_path,’w’)) {
5.             if ($stuff = get_some_stuff()) {
6.                 if (fwrite($fp,$stuff)) {
7.                     // …
8.                 } else {
9.                     return false;
10.                 }
11.             } else {
12.                 return false;
13.             }
14.         } else {
15.             return false;
16.         }
17.     } else {
18.         return false;
19.     }
20. }

1. function do_stuff() {
2. // …
3.     if (!is_writable($folder)) {
4.         return false;
5.     }
6.     if (!$fp = fopen($file_path,’w’)) {
7.         return false;
8.     }
9.     if (!$stuff = get_some_stuff()) {
10.         return false;
11.     }
12.     if (fwrite($fp,$stuff)) {
13.         // …
14.     } else {
15.         return false;
16.     }
17. }

1. SELECT id, username FROM user;
2. UPDATE user SET last_login = NOW()
3. WHERE id = ‘123’
4. SELECT id, username FROM user u
5. LEFT JOIN user_address ua ON(u.id = ua.user_id)
6. WHERE ua.state = ‘NY’
7. GROUP BY u.id
8. ORDER BY u.username
9. LIMIT 0,20

1. <div class=”user_controls”>
2.     <?php if ($user = Current_User::user()): ?>
3.         Hello, <em><?php echo $user->username; ?></em> <br/>
4.         <?php echo anchor(‘logout’, ‘Logout’); ?>
5.     <?php else: ?>
6.         <?php echo anchor(‘login’,’Login’); ?> |
7.         <?php echo anchor(‘signup’, ‘Register’); ?>
8.     <?php endif; ?>
9. </div>
10. <h1>My Message Board</h1>
11. <?php foreach($categories as $category): ?>
12.     <div class=”category”>
13.         <h2><?php echo $category->title; ?></h2>
14.         <?php foreach($category->Forums as $forum): ?>
15.             <div class=”forum”>
16.                 <h3>
17.                     <?php echo anchor(‘forums/’.$forum->id, $forum->title) ?>
18.                     (<?php echo $forum->Threads->count(); ?> threads)
19.                 </h3>
20.                 <div class=”description”>
21.                     <?php echo $forum->description; ?>
22.                 </div>
23.             </div>
24.         <?php endforeach; ?>
25.     </div>
26. <?php endforeach; ?>

1. class User {
2.     public $username;
3.     public $first_name;
4.     public $last_name;
5.     public $email;
6.     public function __construct() {
7.         // …
8.     }
9.     public function create() {
10.         // …
11.     }
12.     public function save() {
13.         // …
14.     }
15.     public function delete() {
16.         // …
17.     }
18. }

1. function capitalize($string) {
2.     $ret = strtoupper($string[0]);
3.     $ret .= strtolower(substr($string,1));
4.     return $ret;
5. }