Comment on page
理解源代码
在这一章中,只打算讨论以命令式编程范型为主的语言,因为其他的编程范型的开源项目,笔者接触太少了(期待各类达人多多补充)。
阅读一个开源项目的源代码,通常都很容易。大多数开源项目的托管网站,都提供了无需下载,直接阅读源代码的功能,比较有趣的是,大家可以比较一下 SourceForge、Google Code以及Github的查看源代码的功能。这分别代表了老、中、青三代开源托管平台,对于查看代码的重视程度。
好的开源项目,通常会选择合理的目录结构,来组织自己的代码。而所谓合理,通常意味着遵循约定俗成的规范。比如:
目录名 | 含义 |
conf/configure | 各种配置文件 |
src/source | 项目的源代码 |
doc/document | 项目文档 |
test/unittest | 单元测试 |
tools/utils | 相关工具 |
lib | 库文件 |
app | 应用相关的文件(在web项目中经常出现) |
controllers | 控制器,在遵循MVC模式的Web项目中,经常出现 |
models | 模型,在遵循MVC模式的Web项目中,经常出现 |
views | 视图,在遵循MVC模式的Web项目中,经常出现 |
db | 数据库相关文件 |
demo/example | 相关示例代码 |
misc | 其他杂项 |
include | 头文件所在目录,C/C++项目中常见 |
out/build | 编译结果输出目录 |
third_party/vender | 第三方库 |
install | 安装所需的相关文件 |
在软件体系中,包(Package)是一个很重要的概念,与模块(Module)类似,但是又有所区别。一个项目,在初始设计时,就需要做模块划分,每一个大小合适的模块,往往就可以作为一个开发工作单元,分配给某个开发者完成。当然,对于那种大型的、复杂的项目,还需对模块做进一步的细分,比如:子模块(Sub Module)。而包(Package),则往往具有一定的可重用性。我们可以认为,一个模块,开源出去未必会有人来用。而一个设计良好的包,本身就可以作为一个开源项目,放出去给被人使用。
因此,从更加有利于软件开发的协作的角度来说,合理的命名包,就变得非常重要。
越是现代的开源项目,越是懂得不必一切从零开始搭建。所以我们常常会发现,一个开源项目,他们自己会开发一组Package,同时也依赖一批别人开发的Package。在静态理解项目时,了解一个项目有哪些包,以及依赖哪些包,就非常重要。
- 首先需要选择查看某一个稳定版本,比如3.2版
- 然后阅读install.rb文件
- 我们可以看到的内容,主要包含两大部分:
- 编译Rails的依赖包:activesupport、activemodel、activerecord、activeresource、actionpack、actionmailer、railties。这些都是Rails项目自己开发的包
- 然后再编译Rails本身
- Rails本身的包描述文件是:rails.gemspec
- 通过阅读rails.gemspec,我们可以了解到,Rails这个项目,依赖的包还包括:bundler、sprockets-rails。
- 事实上,通过阅读activesupport等一系列包的.gemspec文件,我们还会发现更多的外部依赖包。
不同的项目,描述包文件,以及包依赖关系,有各种不同的格式。需要一一分别学习。这里就不再详细解说了。
在一个开源项目中,代码当然是由一个一个的源代码文件组成的。通过查看文件名,往往可以了解一个文件的大概内容。例如:
- errors.rb,通常会与出错处理有关
- i18n.rb,通常会与国际化有关
- logger.rb,通常会与日志有关
- json目录下的两个文件decoding.rb和encoding.rb,自然是JSON格式的编解码相关代码
通常,要迅速的辨认出一个文件名的含义,与领域知识大有关系。例如:http.rb,通常会是处理http协议相关。而request和response,则通常是网络协议中的请求与响应相关的处理代码。对于这些单词的熟悉程度,决定了我们阅读与理解代码的迅捷程度。
Java是一门很讲究规范的语言,所以他的每一个类,就会对应一个同名的.java文件(内部类除外)。这使得我们寻找类所在的源文件,变得非常简单。当然,这样会造成源文件数量的增加,也许会有人不喜欢。
不同的语言,对于命名有其自己的规范,我们可以做一个列表,来简单列出这些规范。
语言 | 包/命名空间命名 | 类命名 | 函数/方法命名 | 常量命名 | 变量命名 |
Java | domainname.package 全部都是小写的单词,以.区隔 | ThisClassName 每个单词都以大写字母开头 | theMethodName 第一个单词以小写字母开头 | THE_VALUE 全部大写,单词以下划线分隔 | theValue 与函数名一致 |
C# | DomainName.Package 每个单词都以大写字母开头,以.区隔 | ThisClassName 每个单词都以大写字母开头 | TheMethondName 与类名一致 | THE_VALUE 全部大写,单词以下划线分隔 | TheValue 与类名一致 |
PHP | domainname.package 全部都是小写的单词,以.区隔 | ThisClassName 每个单词都以大写字母开头 | theMethodName 第一个单词以小写字母开头 | $THE_VALUE 全部大写,单词以下划线分隔 | $theValue 与函数名一致 |
C/C++ | std::hex 全部小写,以::区隔 | CThisClassName 以大写C开头,后续是大写字母开头的单词 | TheMethodName 每个单词以大写字母开头 | nMAX_VALUE 特别会引入前缀的概念,例如:n代表整形、b代表布尔型、c代表字符型等等 | nTheValue 与常量类似,单词区分大小写 |
Delphi | MyUnit.Unit2 遵循Pascal命名法:一个名字里如果包含多个单词,每个单词的首字母都要大写,以.区隔 | TThisClassName 以大写T开头,后续是大写字母开头的单词 | TheMethodName 每个单词以大写字母开头 | castMaxValue 特别会引入前缀的概念,例如:i代表整形、b代表布尔型、c代表字符型等等,cast代表常量 | iTheValue 与常量类似,单词区分大小写 |
Ruby | Module::SubModule 每个单词以大写开头,以::区隔 | ThisClassName 每个单词都以大写字母开头 | the_method_name 全小写单词,以下划线分隔,!?有特定的含义 | MAX_VALUE 全大写单词,以下划线分隔 | the_value 全小写单词,以下划线分隔 |
Python | modsubmod 全部小写,以区隔 | ThisClassName 每个单词都以大写字母开头 | the_method_name/theMethodName 全小写单词,以下划线分隔,也可以类似Java的命名,私有函数以双下划线开头 | MAX_VALUE 全大写,以下划线分隔 | the_value 全小写,以下划线分隔 |
JavaScript | 无 | ThisClassName 每个单词都以大写字母开头 | thePrivateMethod/ThePublicMethod 私有函数小写字母开头,公有函数以大写字母开头 | MAX_VALUE 全大写,下划线分隔 | theValue 小写字母开头,私有变量,加下划线 |
这是一个非常粗略,挂一漏万的表格,详细的命名规范,请参考各种具体语言的命名规范文档。
很多时候,开源项目代码里的注释不仅不会帮助读者理解,反而会带来误导。或者因为语言表述让人不知所云,或者是用特定的缩写符号表示的 只写给自己看的TODO,或者是改了代码而没有改注释,这些反而不利于读者理解代码,甚至造成理解错误。因此我强烈地不建议读者过于重视阅读注释。
但是,在业内有一种流派,非常重视注释,而且信奉从源代码的注释,就可以直接生成项目的开发文档。比如JavaDoc这样的东西,在Java的开源项目里,简直用到泛滥,也造成了Java的很多项目,注释数量比代码的数量还要多。而且,格式规范,千篇一律(为了生成Document),真正有意义的注释内容,少之又少。纯粹是干扰阅读。
很多时候,我都建议阅读代码,就真的去读代码。然后试着从类名、方法名、变量名中,大致“猜出”代码的意义。然后再实际地将代码运行起来,看看执行过程中,这些代码是如何工作的。
总之,不到万不得已,不要先看注释。
虽然我个人对于注释,相当的不重视,但是却非常认同Readme的价值。令我倍感欣慰的是,Github的创立者,也完全赞成这一点。他们将一个项目的首页,直接规定为“代码展示+Readme”,也就强迫所有在Github上安家的开源项目,将更多的精力,投注到Readme的撰写中去。这样形成的良性循环,使得我们可以乐观的预期:越来越多的开源软件,将会越来越重视项目根目录下的Readme文件的价值,将一个项目最为重要的内容,以最为精炼的方式,在Readme中,以结构良好的方式,展现出来。
因此,首先阅读Readme,对于了解一个开源项目,是一个非常好的选择。
UML是一种软件建模语言,全称为:统一建模语言(UML,Unified Modeling Language)。非常巧合的是,在打算写这一小节的今天,@蔡学庸 发了两条微博:
有时候我会一边读源码,一边将我的理解画成图。这是我最近读源码画的图,还没有美化处理。阅读源代码时,将代码顺手图像化,有助于我思考与记忆。位置、色彩、形状,这些都是我将源代码图像化时会采用的手段。
我非常期待,他能够就这个问题,谈到更多的心得。在我看来,在阅读源代码的时候,不断记录,在脑海里形成整个项目的全景图像,是非常有帮助的。
统一建模语言(UML,Unified Modeling Language)是非专利的第三代建模和规约语言。UML是一种开放的方法,用于说明、可视化、构建和编写一个正在开发的、面向对象的、软件密集系统的制品的开放方法。UML展现了一系列最佳工程实践,这些最佳实践在对大规模,复杂系统进行建模方面,特别是在软件架构层次已经被验证有效。UML集成了Booch,OMT和面向对象软件工程的概念,将这些方法融合为单一的,通用的,并且可以广泛使用的建模语言。UML打算成为可以对并发和分布式系统的标准建模语言。UML 并不是一个工业标准,但在Object Management Group的主持和资助下,UML正在逐渐成为工业标准。OMG 之前曾经呼吁业界向其提供有关对象导向的理论及实现的方法,以便制作一个严谨的软件建模语言(Software Modeling Language)。有很多业界的领袖亦真诚地回应OMG,帮助她建立一个业界标准。
在UML系统开发中有三个主要的模型:
- 功能模型: 从用户的角度展示系统的功能,包括用例图。
- 对象模型: 采用对象,属性,操作,关联等概念展示系统的结构和基础,包括类图。
- 动态模型: 展现系统的内部行为。包括序列图,活动图,状态图。
在学习开源软件时如何使用UML,有以下一些经验和忠告:
- 不用使用工具,自动化的生成UML。自己手绘或者用Umbrello这样的开源工具自己绘制,将大大提高阅读并理解代码的能力。
- 首先建立对象的静态模型,也就是先画“类图”。
- 在UML规范之外,可以加一些辅助自己记忆的符号,这个没有一定的规矩,方便好记就行。
- 其次在动态理解的过程中,对关键的执行路径,画出时序图(Sequence Diagram),将有助于深入理解项目的执行过程。
- 对于非面向对象的软件项目,可以参照类图与组件图的模式,画出模块图。也有助于加深理解。
- UML本身有越来越复杂,越来越学术化的倾向,要适可而止。
开源项目的文档水平,有如下几个层次:
- 没有文档(比这个更糟糕的,是有一些错漏的,长时间没有更新的垃圾文档)
- 有一个根据代码注释自动生成的XXDoc,通常这样的文档,价值很低。还不如直接去看代码。
- 有一个简单的综述性质的文档,至少告诉你一个项目的大概。
- 有完整的项目文档,这样的项目已经非常罕见了。
- 有各国志愿者帮助翻译的多语言文档。这样的项目,通常已经是世界一流的项目了。
- 有专门的文档、博客、甚至图书,《XX项目源码解读》之类。一般只有Linux、MySQL这样的项目,才有这样的待遇吧。
一 般来说,外部文档的可信度并不高,而且往往过时。不到走投无路,我不建议找外部文档来帮助理解。当然,一些太复杂的项目,作为入门导引,看看也无妨。
ZoomQuiet补充:可以借用 CMMI 的几个层次来类比出文档的层次:
- 0级: 无文档
- 1级: 号称有文档
- 2级: 有可用文档
- 3级: 文档完备
- 4级: 文档丰富
- 5级: 文档开放,可持续完善
所谓动态理解,就是让项目运行起来,在运行项目的过程中,理解一个项目是如何运行的。(这个有点像绕口令了。。。)
所谓日志,在软件领域,通常是指程序运行的一种记录。开发者与维护人员,可以通过分析日志,了解程序的运行状况。日志输出的数量多寡,可以分为以下几种:
- 完全没有输出(这不是一种好的做法)
- 有出错与崩溃时的输出日志(主要用于排除故障)
- 打开某个参数配置的开关,例如将日志级别修改为debug,将会输出更多的日志信息(主要用于调试程序)
- 为了理解特定的片段,直接修改代码,增加更多的日志输出,甚至将代码执行过程中的所有相关变量,全都输出出来。(用于查找疑难杂症,深入理解源代码等目的。)
ZoomQuiet补充:同前,应该使用相同的递进分析层次
- 0级: 无日志
- 1级: 号称有日志
- 2级: 有可用日志
- 3级: 日志级别完备
- 4级: 日志粒度可调节
- 5级: 有通用日志服务,可集中分析
一个比较完善的开源项目,通常会输出一些日志,如果你搜索整个项目的源代码,都找不到(log,logger,logging)这样的关键字,那就比较糟糕了。
通过修改源代码,以增加更多的日志输出,是我们常用的一种手段,最好是能够找到项目中可供参考的输出日志的办法,照着那个例子来改写。如果实在找不到,或者调用存在一些陷阱,也可以自己纯粹手工地添加日志输出代码。简单的举一个ruby的例子,下面的这一行代码,就可以输出一段内容到日志文件里去了。
File.open("temp.log","a") { |f| f.puts("log info") }
输出日志,能够解决大多数情况下的理解需求,唯一可能会有陷阱的,则是多线程程序输出的日志,因为每次输出的内容可能次序不一致,因此需要特别小心。
IDE有一个重要的好处,就是可以帮助程序员调试程序。在一个图形化界面里,跟踪调试程序,有着纯文字界面难以比拟的便利性。

Netbeans IDE 7.0 调试PHP的程序片段
在一个宽屏的显示器里,同时显示源代码树、对象结构、当前执行到的代码行、当前的各种变量值、调用序列、各个线程、输出内容等等等等,还是很爽的。 当然,要使得IDE能够调试一个开源项目,还是有很多琐碎的事情需要处理。例如:
- 如何在IDE中打开一个项目
- 如何在IDE中配置一个项目的依赖项
- 如何在IDE中编译并运行一个项目
- 如何在IDE中设置断点
这些如何,因语言、平台、IDE、版本、具体项目的不同,而有所区别。这里没法给出一个周到全面的解决方案,但是可以给一些搜索方面的建议:
- 假设要在Netbeans 7中打开一个开源的Java项目,可以搜索“how to open java project in netbeans 7”,然后我们可以找到一些文档:
当然,一定会有各种让人挠头的问题,各位多多尝试吧。另外推荐一本书,是张银奎写的《软件调试》,大部头。但是的确是一本好书!
对于不使用IDE但是想要对代码进行调试的情况,可以通过将每一步的变量进行输出的方式来查看变量的值,或者变量的类型,分析每一步具体输出的变量的值和该值可能进行的操作,这种方式的优点是可以整体性把握程序中变量的处理过程,从头到尾快速追踪一个或几个变量,比较适合于不能添加断点,单步调试比较困难的情况,同时,与添加断点单步调试相比,输出变量的方法可以使不同时期、不同处理过程中的变量同时出现在Console中,可以进行比较直观对比查看某一变量经过某一过程之后发生的变化。
在Python语言中,在对数据进行处理的过程中,我经常会使用输出变量和断点调试相结合的方式进行,因为断点调试中变量的值是实时变化的,想要对其进行对比就可以通过进行输出来对比变化。
有很多种语言,都支持异常处理,以及手动抛出异常。在特定的位置,将整个调用序列打印出来,可以方便我们快速的找到整个项目,是从何处开始,又是如何一层一层的调用,最终到达我们设置抛出异常的位置的。
在Java语言中,我们可以这么写:(new Exception()).printStackTrace(); 在PHP语言中,我们可以直接调用函数:debug_backtrace();或者debug_print_backtrace(); 在Ruby语言中,我们可以这么写:
begin
1/0
rescue => exception
puts exception.backtrace
end
其他种类的语言,建议各位可以自行Google。
在调用了类似的函数之后,我们可以或者类似如下这样的输出:
java.lang.Exception
at org.jruby.lexer.yacc.LexerSource.getSource(LexerSource.java:147)
at org.jruby.parser.Parser.parse(Parser.java:122)
at org.jruby.Ruby.parseFile(Ruby.java:1965)
at org.jruby.Ruby.parseFile(Ruby.java:1969)
at org.jruby.Ruby.parseFromMain(Ruby.java:364)
at org.jruby.Ruby.runFromMain(Ruby.java:327)
at org.jruby.Main.run(Main.java:214)
at org.jruby.Main.run(Main.java:100)
at org.jruby.Main.main(Main.java:84)
以上信息,清楚的现实了某某源文件的某某行,发生了一个调用,进而在下一个源文件中的某个函数,被调用了。于是,我们就可以从抛出异常的代码,开始逐级回溯,阅读相应的代码片段。
在初步理解了项目代码之后,可以尝试做一些简单的修改,看看会发生什么。
- 编译错误
静态类型的语言,在这方面有更多优势,通过编译时给出的错误提示,你可以知道自己改坏了什么,以及为什么它被改坏了。比较令人头痛的,是用了各种复杂的模板语法的C++语言,这时候编译器可能会给出一些令人莫名其妙的报错信息,那你就抓瞎了。不过,开源初学者,一上手就去啃复杂的C++代码,也很难说是明智的选择。
- 运行时报错
与编译期报错类似,你也可以通过阅读一堆一堆的报错信息,了解代码是如何运作的,以及为什么原来不报错,现在就开始报错了。 不过,触发运行时报错,可能会有些困难,这涉及到你修改的代码,是处于主线还是支线位置,以及有多少相关功能,依赖于你所修改的代码。
- 功能失效
可以尝试注释掉一些代码,看看会发生什么事情,比如某个功能按钮失灵甚至消失。当然,对于JavaScript代码,我们常常会 喜欢在某些位置加上alert,看看什么时候会弹出一个消息提示框,却什么事都没有完成。
- 走走捷径
我们常常会看到的一类代码,是长期发展完善后的产物。从接收消息,要处理某某事件开始,到真正去完成某某功能,其间还做了很多的额外工作,比如数据校验,纪录日志,触发其他消息等等,将这些代码全部注释掉,大多数功能都还是正常的,但是,会出各种意外,可以进一步做出各种尝试。(详见5.3. 主线与支线)
有很多辅助代码阅读工具,简单的介绍一些
- IDE类
既然是IDE,自然大多数都已经集成了相当不错的代码阅读功能,索引,反查,标注,自由跳转,通常都应有尽有。比较好的IDE,有Eclipse、Netbeans、IntelliJ IDEA、Visual Studio(Express)等等,各种面向专门语言的IDE还有很多,可以自行在Google搜索“Best XXX IDE”。
- 传统神器+超牛插件