5 理解源代码精品文档28页.docx

资源描述

5 理解源代码精品文档28页.docx

《5 理解源代码精品文档28页.docx》由会员分享，可在线阅读，更多相关《5 理解源代码精品文档28页.docx（23页珍藏版）》请在冰豆网上搜索。

5 理解源代码精品文档28页.docx

5理解源代码精品文档28页

#5.理解源代码

在这一章中，只打算讨论以命令式编程范型为主的语言，因为其他的编程范型的开源项目，笔者接触太少了（期待各类达人多多补充）。

##5.1.静态理解

阅读一个开源项目的源代码，通常都很容易。

大多数开源项目的托管网站，都提供了无需下载，直接阅读源代码的功能，比较有趣的是，大家可以比较一下sourceforge、googlecode以及github的查看源代码的功能。

这分别代表了老、中、青三代开源托管平台，对于查看代码的重视程度。

###5.1.1.目录结构

好的开源项目，通常会选择合理的目录结构，来组织自己的代码。

而所谓合理，通常意味着遵循最常见的约定俗成。

比如：

|目录名|含义|

|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|安装所需的相关文件|

###5.1.2.包名与文件名

在软件体系中，包（Package）是一个很重要的概念，与模块（Module）类似，但是又有所区别。

一个项目，在初始设计时，就需要做模块划分，每一个大小合适的模块，往往就可以作为一个开发工作单元，分配给某个开发者完成。

当然，对于那种大型的、复杂的项目，还需对模块做进一步的细分，比如：

子模块（SubModule）。

而包（Package），则往往具有一定的可重用性。

我们可以认为，一个模块，开源出去未必会有人来用。

而一个设计良好的包，本身就可以作为一个开源项目，放出去给被人使用。

因此，从更加有利于软件开发的协作的角度来说，合理的包命名，就变得非常重要。

越是现代的开源项目，越是懂得不必一切从零开始搭建，所以，我们常常会发现，一个开源项目，他们自己会开发一组Package，同时也依赖一批别人开发的Package。

在静态理解项目时，了解一个项目项目有哪些包，以及依赖哪些包，就非常重要。

举例之一：

rails是一个著名的ruby开源项目。

我们访问它的[github主页]（https:

//github/rails/rails），就可以看到这个项目的源代码结构。

*首先需要选择查看某一个稳定版本，比如3.2版

*https:

//github/rails/rails/tree/3-2-stable

*然后阅读install.rb文件

*https:

//github/rails/rails/blob/3-2-stable/install.rb

*我们可以看到的内容，主要包含两大部分：

*编译rails的依赖包：

activesupport、activemodel、activerecord、activeresource、actionpack、actionmailer、railties。

这些都是rails项目自己开发的包

*然后再编译rails本身

*rails本身的包描述文件是：

rails.gemspec

*https:

//github/rails/rails/blob/3-2-stable/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，则通常是网络协议中的请求与响应相关的处理代码。

对于这些单词的熟悉程度，决定了我们阅读与理解代码的迅捷程度。

###5.1.3.类名、函数名与变量名

java是一门很讲究规范的语言,所以他的每一个类，就会对应一个同名的.java文件（内部类除外）。

这使得我们寻找类所在的源文件，变得非常简单。

当然，这样会造成源文件数量的增加，也许会有人不喜欢。

不同的语言，对于命名有其自己的规范，我们可以做一个列表，来简单列出这些规范。

|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全小写单词，以下划线分隔|

这是一个非常粗略，挂一漏万的表格，详细的命名规范，请参考各种具体语言的命名规范文档。

###5.1.4.注释与Readme

很多时候，开源项目代码里的注释，会给你带来误导。

或者会让人不知所云，或者只是写给自己看到TODO，或者代码改了，注释忘记改。

种种原因，因此我强烈的不建议过于重视注释。

但是，在业内有一种流派，非常重视注释，而且信奉从源代码的注释，就可以直接生成项目的开发文档。

比如JavaDoc这样的东西，在java的开源项目里，简直用到泛滥，也造成了java的很多项目，注释数量比代码的数量还要多。

而且，格式规范，千篇一律（为了生成Document），真正有意义的注释内容，少之又少。

纯粹是干扰阅读。

很多时候，我都建议阅读代码，就真的去读代码。

然后试着从类名、方法名、变量名中，大致“猜出”代码的意义。

然后再实际的将代码运行起来，看看执行过程中，这些代码是如何工作的。

总之，不到万不得已，不要先看注释。

虽然我个人对于注释，相当的不重视，但是却非常认同Readme的价值。

令我倍感欣慰的是，Github的创立者，也完全赞成这一点。

他们将一个项目的首页，直接规定为“代码展示+Readme”，也就强迫所有在Github上安家的开源项目，将更多的精力，投注到Readme的撰写中去。

这样形成的良性循环，使得我们可以乐观的预期：

越来越多的开源软件，将会越来越重视项目根目录下的Readme文件的价值，将一个项目最为重要的内容，以最为精炼的方式，在Readme中，以结构良好的方式，展现出来。

因此，首先阅读Readme，对于了解一个开源项目，是一个非常好的选择。

###5.1.5.UML图

UML是一种软件建模语言，全称为：

统一建模语言（UML，UnifiedModelingLanguage）。

非常巧合的是，在打算写这一小节的今天，@蔡学庸发了两条微博：

>有时候我会一边读源码，一边将我的理解画成图。

这是我最近读源码画的图，还没有美化处理。

>阅读源代码时，将代码顺手图像化，有助于我思考与记忆。

位置、色彩、形状，这些都是我将源代码图像化时会采用的手段。

我非常期待，他能够就这个问题，谈到更多的心得。

在我看来，在阅读源代码的时候，不断记录，在脑海里形成整个项目的全景图像，是非常有帮助的。

关于UML的定义，可以参考维基百科：

[UML]（http:

//zh.wikipedia.org/wiki/UML），以下引用一段：

>统一建模语言（UML，UnifiedModelingLanguage）是非专利的第三代建模和规约语言。

UML是一种开放的方法，用于说明、可视化、构建和编写一个正在开发的、面向对象的、软件密集系统的制品的开放方法。

UML展现了一系列最佳工程实践，这些最佳实践在对大规模，复杂系统进行建模方面，特别是在软件架构层次已经被验证有效。

>UML集成了Booch，OMT和面向对象软件工程的概念，将这些方法融合为单一的，通用的，并且可以广泛使用的建模语言。

UML打算成为可以对并发和分布式系统的标准建模语言。

>UML并不是一个工业标准，但在ObjectManagementGroup的主持和资助下，UML正在逐渐成为工业标准。

OMG之前曾经呼吁业界向其提供有关对象导向的理论及实现的方法，以便制作一个严谨的软件建模语言（SoftwareModelingLanguage）。

>有很多业界的领袖亦真诚地回应OMG，帮助她建立一个业界标准。

在UML系统开发中有三个主要的模型：

***功能模型**：

从用户的角度展示系统的功能，包括用例图。

***对象模型**：

采用对象，属性，操作，关联等概念展示系统的结构和基础，包括类图。

***动态模型**：

展现系统的内部行为。

包括序列图，活动图，状态图。

在学习开源软件时如何使用UML，有以下一些经验和忠告：

*不用使用工具，自动化的生成UML。

自己手绘或者用Umbrello这样的开源工具自己绘制，将大大提高阅读并理解代码的能力。

*首先建立对象的静态模型，也就是先画“类图”。

*在UML规范之外，可以加一些辅助自己记忆的符号，这个没有一定的规矩，方便好记就行。

*其次在动态理解的过程中，对关键的执行路径，画出时序图（SequenceDiagram），将有助于深入理解项目的执行过程。

*对于非面向对象的软件项目，可以参照类图与组件图的模式，画出模块图。

也有助于加深理解。

*UML本身有越来越复杂，越来越学术化的倾向，要适可而止。

###5.1.6.外部文档

开源项目的文档水平，有如下几个层次：

*没有文档（比这个更糟糕的，是有一些错漏的，长时间没有更新的垃圾文档）

*有一个根据代码注释自动生成的XXDoc，通常这样的文档，价值很低。

还不如直接去看代码。

*有一个简单的综述性质的文档，至少告诉你一个项目的大概。

*有完整的项目文档，这样的项目已经非常罕见了。

*有各国志愿者帮助翻译的多语言文档。

这样的项目，通常已经是世界一流的项目了。

*有专门的文档、博客、甚至图书，《XX项目源码解读》之类。

一般只有Linux、MySQL这样的项目，才有这样的待遇吧。

一般来说，外部文档的可信度并不高，而且往往过时。

不到走投无路，我不建议找外部文档来帮助理解。

当然，一些太复杂的项目，作为入门导引，看看也无妨。

ZoomQuiet补充：

可以借用CMMI的几个层次来类比出文档的层次:

*0级:

无文档

*1级:

号称有文档

*2级:

有可用文档

*3级:

文档完备

*4级:

文档丰富

*5级:

文档开放,可持续完善

##5.2.动态理解

所谓动态理解，就是让项目运行起来，在运行项目的过程中，理解一个项目是如何运行的。

（这个有点像绕口令了。

。

）

###5.2.1.输出日志

所谓日志，在软件领域，通常是指程序运行的一种记录。

开发者与维护人员，可以通过分析日志，了解程序的运行状况。

日志输出的数量多寡，可以分为以下几种：

*完全没有输出（这不是一种好的做法）

*有出错与崩溃时的输出日志（主要用于排除故障）

*打开某个参数配置的开关，例如将日志级别修改为debug，将会输出更多的日志信息（主要用于调试程序）

*为了理解特定的片段，直接修改代码，增加更多的日志输出，甚至将代码执行过程中的所有相关变量，全都输出出来。

（用于查找疑难杂症，深入理解源代码等目的。

）

ZoomQuiet补充：

同前,应该使用相同的递进分析层次

*0级:

无日志

*1级:

号称有日志

*2级:

有可用日志

*3级:

日志级别完备

*4级:

日志粒度可调节

*5级:

有通用日志服务,可集中分析

一个比较完善的开源项目，通常会输出一些日志，如果你搜索整个项目的源代码，都找不到（log，logger，logging）这样的关键字，那就比较糟糕了。

通过修改源代码，以增加更多的日志输出，是我们常用的一种手段，最好是能够找到项目中可供参考的输出日志的办法，照着那个例子来改写。

如果实在找不到，或者调用存在一些陷阱，也可以自己纯粹手工的添加日志输出代码。

简单的举一个ruby的例子，下面的这一行代码，就可以输出一段内容到日志文件里去了。

File.open（"temp.log","a"）{|f|f.puts（"loginfo"）}

输出日志，能够解决大多数情况下的理解需求，唯一可能会有陷阱的，则是**多线程程序输出的日志**，因为每次输出的内容可能次序不一致，因此需要特别小心。

###5.2.2.设置断点与单步跟踪

IDE有一个重要的好处，就是可以帮助程序员调试程序。

在一个图形化界面里，跟踪调试程序，有着纯文字界面难以比拟的便利性。

[]（images/debug-NetBeans-IDE-7.0.png）

NetbeansIDE7.0调试PHP的程序片段

在一个宽屏的显示器里，同时显示源代码树、对象结构、当前执行到的代码行、当前的各种变量值、调用序列、各个线程、输出内容等等等等，还是很爽的。

当然，要使得IDE能够调试一个开源项目，还是有很多琐碎的事情需要处理。

例如：

*如何在IDE中打开一个项目

*如何在IDE中配置一个项目的依赖项

*如何在IDE中编译并运行一个项目

*如何在IDE中设置断点

这些如何，因语言、平台、IDE、版本、具体项目的不同，而有所区别。

这里没法给出一个周到全面的解决方案，但是可以给一些搜索方面的建议：

*假设要在Netbeans7中打开一个开源的Java项目，可以搜索“howtoopenjavaprojectinnetbeans7”，然后我们可以找到一些文档：

*http:

//netbeans.org/kb/docs/java/project-setup.html

*http:

//stackoverflow/questions/4382619/how-can-i-open-non-netbeans-java-project-using-netbeans

当然，一定会有各种让人挠头的问题，各位多多尝试吧。

另外推荐一本书，是张银奎写的《软件调试》，大部头。

但是的确是一本好书！

http:

//book.douban/subject/3088353/

###5.2.3.抛出异常

有很多种语言，都支持异常处理，以及手动抛出异常。

在特定的位置，将整个调用序列打印出来，可以方便我们快速的找到整个项目，是从何处开始，又是如何一层一层的调用，最终到达我们设置抛出异常的位置的。

在Java语言中，我们可以这么写：

（newException（））.printStackTrace（）;

在PHP语言中，我们可以直接调用函数：

debug_backtrace（）;或者debug_print_backtrace（）;

在Ruby语言中，我们可以这么写：

begin

1/0

rescue=>exception

putsexception.backtrace

end

其他种类的语言，建议各位可以自行Google。

在调用了类似的函数之后，我们可以或者类似如下这样的输出：

java.lang.Exception

atorg.jruby.lexer.yacc.LexerSource.getSource（LexerSource.java:

147）

atorg.jruby.parser.Parser.parse（Parser.java:

122）

atorg.jruby.Ruby.parseFile（Ruby.java:

1965）

atorg.jruby.Ruby.parseFile（Ruby.java:

1969）

atorg.jruby.Ruby.parseFromMain（Ruby.java:

364）

atorg.jruby.Ruby.runFromMain（Ruby.java:

327）

atorg.jruby.Main.run（Main.java:

214）

atorg.jruby.Main.run（Main.java:

100）

atorg.jruby.Main.main（Main.java:

84）

以上信息，清楚的现实了某某源文件的某某行，发生了一个调用，进而在下一个源文件中的某个函数，被调用了。

于是，我们就可以从抛出异常的代码，开始逐级回溯，阅读相应的代码片段。

###5.2.4.修改代码，破坏性尝试

在初步理解了项目代码之后，可以尝试做一些简单的修改，看看会发生什么。

*编译错误

静态类型的语言，在这方面有更多优势，通过编译时给出的错误提示，你可以知道自己改坏了什么，以及为什么它被改坏了。

比较令人头痛的，是用了各种复杂的模板语法的C++语言，这时候编译器可能会给出一些令人莫名其妙的报错信息，那你就抓瞎了。

不过，开源初学者，一上手就去啃复杂的C++代码，也很难说是明智的选择。

*运行时报错

与编译期报错类似，你也可以通过阅读一堆一堆的报错信息，了解代码是如何运作的，以及为什么原来不报错，现在就开始报错了。

不过，触发运行时报错，可能会有些困难，这涉及到你修改的代码，是处于主线还是支线位置，以及有多少相关功能，依赖于你所修改的代码。

*功能失效

可以尝试注释掉一些代码，看看会发生什么事情，比如某个功能按钮失灵甚至消失。

当然，对于JavaScript代码，我们常常会喜欢在某些位置加上alert，看看什么时候会弹出一个消息提示框，缺什么事都没有完成。

*走走捷径

我们常常会看到的一类代码，是长期发展完善后的产物。

从接收消息，要处理某某事件开始，到真正去完成某某功能，其间还做了很多的额外工作，比如数据校验，纪录日志，触发其他消息等等，将这些代码全部注释掉，大多数功能都还是正常的，但是，会出各种意外，可以进一步做出各种尝试。

（详见5.3.主线与支线）

###5.2.5.工具

有很多辅助代码阅读工具，简单的介绍一些

*IDE类

既然是IDE，自然大多数都已经集成了相当不错的代码阅读功能，索引，反查，标注，自由跳转，通常都应有尽有。

比较好的IDE，有Eclipse、Netbeans、IntelliJIDEA、VisualStudio（Express）等等，各种面向专门语言的IDE还有很多，可以自行在Google搜索“BestXXXIDE”。

进阶阅读：

[18个最佳代码编辑器/IDE推荐]（http:

//iteye/news/24235）

*传统神器＋超牛插件

所谓传统神器，自然是指Emacs与VIM，这两款神器不能简单的以是否IDE来划分。

他们都带有众多的插件，可以扩展出惊人的灵活性。

推荐阅读两篇文章：

[Emacs和它的朋友们——阅读源代码篇]（http:

//baohaojun.github/reading-source-code-cn）

[自己动手定制一个高效阅读源代码的vim]（http:

//zqwt.012.blog.163/blog/static/1204468420114194264789/）

*专业工具

专业工具，通常也是由商业公司开发的收费软件，人家要挣钱，自然也要有拿得出手的好东西。

这里推荐两款软件，更多介绍，请自行搜索相关介绍与教程：

*[Understand]（http:

//scitools/index.php）

*[sourceinsight]（http:

//sourceinsight/）

*软件工程相关工具

所谓软件工程的相关工具，主要是一些与面向对象概念相关的UML工具，比如IBM的RationalRose、Sybase的PowerDesinger、还有Borland的Together，都是大公司出品的一些大家伙。

可以将面向对象语言（主要是Java）的项目，转换输出成为UML的各种图，有一定的参考价值，玩玩也不错。

##5.3.主线与支线

一个开源项目，我们总可以从中找到主要的功能与次要的、辅助的功能。

一个系统从启动开始，到完成最核心的功能、任务，最后成功结束，就是一条主

展开阅读全文