好的命名是最好的文档

好的命名是最好的文档。包括：

项目名
模块名
变量名
函数名
类名
…

最近接手了一个上古项目，没有任何文档，很多变量名都是一些比较泛的名字，导致维护的时候，理解起来非常困难。再加上项目是前后端分离，为了修复一个接口，要同时理解两个毫无文档的上古项目。在这里我们看看坏的命名风格，以从中吸取经验教训，防止再次踩坑。

项目名不应该用代号

很多项目其实都是使用一个电影或者动漫等的人名，物名等作为项目名。例如 bb8, c3po, nagato等等。仍然记得此前使用朴素简单的项目名，被项目leader吐槽“俗”，但是现在看来，simple is better，例如推送系统可能就叫 xxx_push，xxx 是部门名字，朴素吗？朴素。易懂吗？易懂，一看就能反映出部门名与主要作用。

模块名更应该拒绝使用代号

比如我正在处理的这个上古项目，其模块名为 c3po, bb8。一眼看去，没有看过《星球大战》的人谁能知道是什么意思？这个模块是做什么用的？即使是看过这个电影的人，也无法猜测出该模块的具体作用。好的命名应该是简单易懂的，例如：controller, models。

拒绝使用拼音缩写

使用拼音的全拼都比缩写易懂的多，当然，也是需要很长时间去理解的。最好还是按照约定，使用英文。

拒绝使用缩写，即便是长命名也比缩写好的多

有的时候描述一个变量，或者类，的确会使用比较长的词语才能描述完，但是，仍然比使用缩写会好的多，例如 lock_for_user，而不应该使用非通用的自创缩写 lk4user 等等。的确这样可以少写几个单词，但是对于团队内协作，损耗远比收益大。

驼峰还是下划线，遵循组内规定即可

这一点倒是没有在上古项目中体现出来，我在这仅仅是提出来。驼峰还是下划线，其实就像是大端还是小端，vim还是emacs一样，是一个争不出结论的话题。一句话：遵循项目约定，团队约定，语言官方推荐约定即可。

README 应该写项目相关的内容

说回这个上古项目，它的 README 是这样的：

使用 XXXX 和 YYYY 代替具体项目名，下同

$ cat README.md 
# XXXX后端

而它的一个兄弟项目，README 是这样的：

# YYYY -- XXXX的好基友

install nodejs
install npm


`cd XXXX`

`npm install -g webpack`

`npm install`

`webpack -w --display-error-details`


`sudo ln -s "$(which nodejs)" /usr/bin/node` 被坑了

nodejs 下载不下来 sad

再也没有其它文档了，如果你来维护这样的项目，请问，如何看懂？

一个好的README应该是写这个项目是做什么用的，代码组织结构，如何使用，其它文档在哪，如何阅读等等。

项目文档应该跟着代码走而不是保存在第三方

很多公司都使用 confluence + jira 全家桶。不可避免的就喜欢把项目文档放到 confluence 上，但是我仍然坚持应该把项目文档例如需求，API等放到代码仓库中。当然，API为了共享，可以单独开仓库。这样做有多种好处，例如文档变更可追溯，读代码就能读文档等等。

总结

好的文档，好的命名，在你自己写一个项目的时候，是看不出什么效果的，它只体现在维护者的上手难度上。当然了，我以前写的很多项目，也没有能够好好的做好上述要求，只能对维护者说一声抱歉。

好的命名，就是最好的文档。

参考资料：