好的命名是最好的文档

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

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

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

项目名不应该用代号

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

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

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

拒绝使用拼音缩写

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

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

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

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

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

README 应该写项目相关的内容

说回这个上古项目,它的 README 是这样的:

使用 XXXXYYYY 代替具体项目名,下同

$ 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为了共享,可以单独开仓库。这样做有多种好处,例如文档变更可追溯,读代码就能读文档等等。

总结

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

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


参考资料:


更多文章
  • 读《影响力》
  • 读《自控力》
  • Containerd简明教程
  • 软件设计套路之推拉模式
  • 记一次Golang TLS编程踩坑
  • 杂谈
  • 使用autossh实现内网穿透
  • Linux线程内存模型
  • 关闭手机通知,修复碎片化的生活
  • Linux下系统调用的过程