掌握 10 个小贴士,Max 你的代码可读性!

导语:在敏捷开发环境下,确保代码能被别人读懂是至关重要的。想要让你的代码不再看起来那么天书?希望这些小贴士能帮到你。

作者:Manas Sadangi

译者:欧剃

让代码清晰易读不单单是为了别人,也是为了你自己调试自己的程序的时候,少死一些脑细胞。

其实,在计算机编程的世界中,代码可读性是个相当普遍的话题。在我们初涉开发的门径时,它就是最先要学的东西之一。本文将具体阐述一些在提升代码可读性方面又好又重要的实践经验,希望对你有帮助。

01

做好注释和文档

Commenting and Documentation

打个不太恰当的比方,给你的代码做注释,就好比清理你家的厕所。如果你花了点时间做了,那绝对会给你自己和你的客人带来更愉悦的体验。

许多IDE(集成开发环境)在过去几年里已经有了长足的进展。给代码加注释这件事在IDE的帮助下变得比以往都要简单。只要你的注释按照某些标准来写,IDE和其他工具就能用各种方式来利用这些注释帮助你。

举个例子:

我在函数定义前面增加了相关注释之后,不论我在什么地方使用这个函数(即使在其他文件里),我都能方便地看到这个函数的说明。

再举一个例子,我调用一个第三方库里包含的函数,IDE就为我显示出具体的用法和说明:

在这几个例子里,我使用的注释(或文档)的格式是基于PHPDoc的,使用的IDE是Aptana。

相信我,三个月以后的你会感谢现在的你做了注释的。

02

保持缩进风格一致

Consistent Indentation

我想,大家应该都知道应该要缩进自己的代码吧?然而,同样需要注意的是,保持你的缩进风格始终一致也是个好主意。

缩进代码的风格可以有很多种,下面是比较常见的两种缩进样式:

我以前曾用下面的样式2,不过最近全部切换到了样式1。当然,这只是一个喜好问题,并没有什么所有人都必须遵守的“最佳”缩进样式。事实上,保持不变就是最好的样式。如果你是团队的一员,或者你在为某个项目贡献代码,你应该遵循那个项目已有代码中的缩进样式。

各种缩进风格之间,也并非就一定是水火不容的。有的缩进样式还会混合多种不同风格的缩进规则。比如,在PHP扩展及应用程序仓库(PEAR)的代码规范里,跟在控制结构语句后面的大括号“{”不换行,而在函数体外侧的大括号则是换行的。

还要注意,他们的缩进是用4个空格,而不是一个制表符(Tab)。维基百科上有一篇文章介绍了不同风格的缩进样式。

03

避免没话找话的注释

Avoid Obvious Comments

注释代码是一件很棒的事; 然而,要避免过度注释,或是明显废话的注释。

举个例子:

当代码本身就已经很明确地说明了自身用途的时候,再专门用注释重复一遍一摸一样的话显然是在浪费时间。

如果你必须给这段代码加注释,你可以简单地用一句话概括一下这段代码的用途:

04

组织好代码段落

Code Grouping

相当常见的情况是,某一个任务需要若干行代码来完成。我建议可以将每个这样的段落都放在一个单独的语句块中,互相之间用空行隔开。

举个简化过的例子:

在每个代码块的开头增加一行注释,也可以强化语句块间的视觉分割。

05

保持命名规则一致

Consistent Naming Scheme

PHP本身有时就该为没有保持一致的命名规则负有责任,比如:

● strpos() 和 str_split()

● imagetypes() 和 image_type_to_extension()

首先,名字中的单词之间应该有可辨识的界限。常见的有两种方式:

● 驼峰式命名法(camelCase):除第一个单词之外,其他每个单词的首字母大写。

● 下划线法:单词之间用下划线连接,比如:mysql_real_escape_string()。

因为有多种可选的命名规则,所以这个状况很像我之前提到的缩进风格的问题。如果某个已有的项目的代码遵循某个惯例,你也应当和它保持一致。同时,如果某个语言本身就倾向于采用某种命名规则,你也最好保持同样的习惯。比如,Java里大部分的代码都用驼峰式命名法,而在PHP里,程序员们更多会采用下划线。

同样,这两者也可以混合使用。有些程序员喜欢用下划线给过程函数和类命名,但给类的方法命名时就更倾向于用驼峰式命名法:

同样,这也没有什么一定是“最好”的命名法,主要是你得保持前后一致。

06

DRY原则

DRY Principle

这里DRY代表Don't Repeat Yourself(不要重复你自己)。也有人把它称作DIE:Duplication is Evil(复制是邪恶的)。具体来说,就是:

“系统中的每一部分,都必须有一个单一的、明确的、权威的代表。”

大部分应用程序(或者统称计算机)的设计目的就是自动完成重复的工作。你在所有的代码——甚至是网页应用中——都应该保持这个原则。同一块代码不应该被复制来复制去的。

举例来说,大部分的网页应用程序都由许多页面组成,这些页面很大程度上都包含着共同的元素,最常见的比如每个网页的头部和尾部。如果在每个页面间都要复制粘贴这些头尾部分,那可不是什么好主意。Jeffrey Way 就解释过在 CodeIgniter 里要如何生成页面模板:

07

避免嵌套层数过深

Avoid Deep Nesting

嵌套层数太多会让你的代码难以阅读和理解。

为了保证可读性,通常你必须调整代码,减少嵌套的层数:

08

控制每行的长度

Limit Line Length

人类的眼睛在阅读长条的列状文本时更为舒适。这也正是为什么报纸要这样排版:

所以,避免写出横向太长的代码行是一种很好的行为。

同时,如果其他人打算在终端窗口内阅读你的代码,比如VIM用户,你最好能将每行的宽度限制在大约80个字符内。

09

文件和目录组织

File and Folder Organization

技术上来说,你可以把整个应用的代码全部写在单个文件里。不过那将会使阅读和维护代码变成一场噩梦。

在我最初的编程项目中,我其实已经知道要构建“包含文件”这样的东西。

然而,我当时却连一丁点条理都没有。我建立了一个“inc”文件夹,里面就两个文件: dp.php 和 functions.php。随着应用的完善,那个函数文件变得无比巨大而且根本无法维护。

最好的处理办法,要么采用一个成熟的框架,或者模仿它们的目录结构。比如 CodeIgniter 的结构是这样的:

10

保持一致的临时变量名

Consistent Temporary Names

正常来说,变量名应当是描述性的,并且包含一个或更多个单词,并遵循上面说到的那些命名规则。但是,这对一些临时性的变量来说是不必要的。临时变量可以短到用一个字幕来命名。但你最好还是保持始终给同种用途的临时变量赋予一致的临时变量名。这里有一些我在代码中常用的实例:

— 完 —

我来评几句
登录后评论

已发表评论数()

相关站点

+订阅
热门文章