好的命名是最好的文档
好的命名是最好的文档。包括:
- 项目名
- 模块名
- 变量名
- 函数名
- 类名
- …
最近接手了一个上古项目,没有任何文档,很多变量名都是一些比较泛的名字,导致维护的时候,理解起来非常困难。再加上项目是 前后端分离,为了修复一个接口,要同时理解两个毫无文档的上古项目。在这里我们看看坏的命名风格,以从中吸取经验教训,防止再次踩坑。
项目名不应该用代号
很多项目其实都是使用一个电影或者动漫等的人名,物名等作为项目名。例如 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为了共享,可以单独开仓库。这样做有多种好处,例如文档变更可追溯,读代码就能读文档等等。
总结
好的文档,好的命名,在你自己写一个项目的时候,是看不出什么效果的,它只体现在维护者的上手难度上。当然了,我以前写的很多 项目,也没有能够好好的做好上述要求,只能对维护者说一声抱歉。
好的命名,就是最好的文档。
参考资料:
更多文章
- socks5 协议详解
- zerotier简明教程
- 搞定面试中的系统设计题
- 用peewee代替SQLAlchemy
- frp 源码阅读与分析(一):流程和概念
- Golang(Go语言)中实现典型的fork调用
- DNSCrypt简明教程
- 一个Gunicorn worker数量引发的血案
- Golang validator使用教程
- Docker组件介绍(一):runc和containerd
- Docker组件介绍(二):shim, docker-init和docker-proxy
- 使用Go语言实现一个异步任务框架
- 协程(coroutine)简介 - 什么是协程?
- SQLAlchemy简明教程
- Go Module 简明教程