被忽略的关键信息

Experience

在前端领域内,框架及工具库的百花齐放,不仅提高了我们的日常工作效率,同时也为后来者提供了优秀的学习素材。通过优秀开源项目源码的阅读与学习,我们能够从中吸收最佳实践、框架设计思想、奇技淫巧等知识,并为我所用,助我升职加薪。

通常而言,我们不会在对一个框架或库一无所知的情况下,就直接一头栽到庞杂的源码中去,毕竟干嚼馒头并不甜。相反,源码阅读一定要建立在自己已经对目标项目有所认知,最好能够熟练使用的基础上。通过日常使用,发现其中的某些功能或实现非常值得学习,再开始源码的阅读之旅,往往能够事半功倍。

而对于前端项目而言,阅读完 README.md 之后,拿到源码,需要阅读的第一个文件往往是该项目的描述文件 ——package.json 文件。在其中,我们能够找到项目的入口文件( main )是什么,依赖( dependencies )及开发依赖( devDependencies )有哪些,以及有哪些可供使用的( scripts )脚本。知道了这些,就相当于参观景区时,找到了景区的入口。从入口开始,按图索骥就能够完整的浏览完整个景区。但在浏览的过程中,我们只能看到眼前的景观,无法对景区的整体分布及行进路径了然于胸,故而容易迷路及重复走同一条路,效率不高。

阅读源码也一样,main 指定了项目入口,从入口文件开始,按照文件索引关系,也能完成源码的阅读。按照此方法阅读,我们能看清更多的实现细节,但也更容易陷入实现细节之中,拖慢阅读进度。同时,因缺少对项目整体架构的认识,脱离项目整体去看细节,往往会造成理解上的困扰,当这种困扰积少成多时,阅读积极性则会受到致命打击。这种阅读方法,只适合那些对源码已经有所了解同学使用。

这个时候,我们就需要在浏览景区之前,找到景区的浏览全景地图。那怎么才能在开始阅读源码前,找到项目的全景图呢?我之前的做法是在网上搜索别人的阅读笔记,久而久之发现这种做法效率较低:

  • 一是信息检索筛选耗费时间精力
  • 二是要核对他人的阅读笔记所基于的项目版本要与自己要阅读的版本一致
  • 三是,网络信息质量与准确性无法保证
  • 四是,他人消化后的二手信息总没有自己理解后的内容来的深刻

最近,在阅读 Vue 源码的过程中偶然间发现,之前一直当作隐藏/配置文件而被忽略的 .github 文件夹里却藏着「官方的项目全景图」。一般而言,开源共建项目都会包含该目录,目录下包含但不限于如下内容:

文件名功能描述
ISSUE_TEMPLATE.mdIssues 模版
PULL_REQUEST_TEMPLATE.mdPull Requests 模版
CONTRIBUTING.md代码贡献指引
......

这些文件,望文生义,向开发者描述了如果向当前项目提 issue、发起 PR,以及如何贡献代码。因此,我们主要关注 CONTRIBUTING.md 文件,该文件向开发者描述了如何启动、调试项目。Vue 同时也向开发者介绍了 项目结构

这便是我们要找寻的「项目全景图」,它比任何其他个人的阅读笔记更加准确、清晰、具有关键的概括性。从而帮助我们在阅读的过程中,准确排除干扰信息,不被细节羁绊,紧抓主线。

除此之外,如果项目中存在 examplestest 目录,其中一般存放简短的示例文件,或者单一功能的测试文件,也建议在进入正式的源码阅读之前,能够快速浏览下该目录的内容,不失为阅读前的一项不错的热身运动。

如有任何问题或建议,欢迎在issues中交流讨论