一个完整的项目是怎样的

你可曾碰到一些项目，路径下就一个 src，或者是一个 lib。

也许是要用到这个项目，也许是要接盘这个项目，但不管怎样，看到这个项目根目录的时候，你已经绝望了

那一个完整的，易上手的项目是怎样的？

我们不妨来看看 gnu/coreutil(git://git.sv.gnu.org/coreutils) 这个项目的目录

~/coreutils$ tree -L 1
.
├── AUTHORS
├── bootstrap
├── bootstrap.conf
├── build-aux
├── cfg.mk
├── ChangeLog-2005
...
├── README
├── README-hacking
├── README-package-renamed-to-coreutils
├── README-prereq
├── README-release
├── README-valgrind
├── scripts
├── src
├── tests
├── thanks-gen
├── THANKS.in
├── THANKStt.in
└── TODO

这的确是个完整的项目呐，各种文档各种说明应有尽有

代码目录 src lib
文档路径 doc
测试路径 tests
ChangeLog 按年份分好
Makefile Makefile.am bootstrap
readme

可以看到在 coreutils 中光是 README 就有 6 个，比如 README-hacking 就是给工程师看的

readme

readme 相当于是一个项目的入口，使用一个项目大家一般会习惯性的先找 readme，没有 readme 的项目就像一瓶没有说明书的药丸，没人敢吃

readme 应该包含这些信息，例如安装方法，使用方法，如果是库还应该带上文档

tests

tests 也是项目中重要的一环，它证明了这个项目的代码是可用的，是经过检验的， tests 也能给接盘侠充分的信心，人们不再需要修改一个小点的时候胆战心惊，瞻前顾后，因为 make test 会把检查结果告诉他

coverage

覆盖率顾名思义就是代码测试是否全面的一个指标，测试只告诉你哪些 cases 能通过测试，而没有告诉你哪些代码是可以用的

有不少时候开发者会写一些将来可能会用到，但现在没用到的代码，却忘了把他们注释起来，但其他开发者并不知道，如果他们贸然使用这些从来没运行过的代码，很有可能会造成 bug

我们不妨拿 min-util 这个项目作为范例

min-util 的 readme 中的这么多 badge 分别表示

build passing travis 持续集成通过
npm v1.x.x 当前项目的版本号
downloads 1k/month 每月下载量
dependencies up-to-date 依赖是最新的（这点不理解的可以去看 semver 版本管理）
coverage 99% 覆盖率为99%

后面的 Installation 和 Usage 分别交代了安装方法与使用方法

由于 min-util 是一个小型 js 基础库，因为也带上了简单的 API 文档

min-util 麻雀虽小，全部仅有300多行，却是五脏俱全

travis 持续集成

上面 readme 里面说 min-util 是支持 IE6+ 的库，因此也在测试里面带有 IE6-8 的测试，证明了它确实可以运行在 IE6 中

coverage

在 coverall 服务上，测试覆盖率一目了然，绿色表示运行过的，红色表示没运行过的，这上面的截图就可以看出 _.create(null) 并没有运行过，因此也肯定没有测试过，也许连项目的主人都不知道是否可以用，因此，使用者更不该去用这个函数

其实 min-util 并不算一个小项目，可以看一个更小的项目 muid, 一个生成 unique id 的库，虽然只有9行，却依然有着完整的测试和 readme

总结

我们希望几个月后甚至是数十年后，当别人翻看自己的项目，只需淡定的点根烟，扫一眼 readme，敲几下键盘就能跑起来，并放心的使用。而不是看着 wiki，开着百度，打着断点却依然不知道这代码到底写的是啥玩意儿

chunpu / blog