程序员为啥不爱写文档？问就是代码即文档
产品经理："这功能怎么用的呀？" 程序员："看代码啊，代码就是最好的文档。"
有个名场面，你肯定见过
产品经理走过来："小王，这个接口的文档写好了吗？对接方在催了。"
程序员小王头都不抬："在写了在写了。"
实际上，他的 IDE 里光标在一个空白文档上闪了三天，连个字都没动。
三天后，文档终于发了过去：
POST /api/user参数：JSON返回：JSON
产品经理看完："这也能叫做文档？
小王淡定地说："代码都注释了，自己看去。"
真相只有一个：写代码爽，写文档痛苦
配图提示词：对比图，左边程序员写代码笑容满面，右边写文档痛苦面具，冷暖色调对比
说到底，程序员不爱写文档，核心原因就一个——这玩意儿不爽。
你想想：
写代码的时候
写文档的时候
同样是创造，一个是盖楼，一个是填表。换你，你选哪个？
那些年我们用过的借口
程序员不写文档，理由能说出一火车。
最经典的就是这句："代码就是最好的文档。"
说这话的时候理直气壮："我的代码写得这么清晰，变量命名这么规范，看代码不就完了？"
现实呢？ 三个月后你自己看自己的代码，盯着屏幕足足五分钟，心里就一个想法——"这哪个傻X写的？"
还有人说："文档永远滞后于代码。今天改了明天改，写那玩意儿不是浪费时间吗？等稳定了再写。"
问题是，"稳定"的那一天永远不会来。等项目结束，文档还是一张白纸。
更绝的是这种说法："看文档不如直接问我。文档写得再详细，遇到问题还是得找我，直接问效率更高。"
直到——你休年假去马尔代夫躺沙滩，团队群里消息炸了锅，所有人都在问同一个问题，而你在千里之外只能干瞪眼。
还有一个理由挺有迷惑性："API 调用这么简单，看个 demo 就懂了，写什么文档。"
然后 新人入职第一周，光搞懂这个接口怎么调就秃了头，最后跑来问："哥，有文档吗？demo 看不太懂。"
写文档这事儿，有多痛苦？
周一早会，项目主管提了一嘴："小王，那个接口的文档这周能搞定不？"
小王点头如捣蒜："没问题，周五前给。"
心里想的是：拖到周四再说。
周三过了，没啥动静。
周四下午，主管路过工位，随口问了句："文档进度咋样了？"
"快了快了，"小王头都没抬，"在收尾。"
实际上，连个文档标题都还没建。
周四晚上 9 点，主管在群里发了条消息："对接方说明早就要文档，今晚必须给。"
那一刻，小王的内心是崩溃的。
打开编辑器，新建文档，光标在空白页面上闪啊闪。
"这个接口……叫啥来着？"
翻回去看代码。
getUserInfo……哦，对，获取用户信息。
"参数有哪些来着？"
再看代码。
id, type, includeDeleted……三个参数。
"每个参数是干嘛的？"
再……看代码。
看了半天，自己都看笑了——这代码当初是我写的吗？
两小时后，一份"文档"诞生了：
// 用户登录接口// 参数：用户名、密码// 返回：成功/失败{ "code": 200, // 200表示成功 "msg": "成功"}
发过去。
五秒后，主管回了条消息："就这？"
小王回得理直气壮："能跑就行，要啥自行车。"
更扎心的是：写了也没人看
更绝的是什么？——你终于把文档肝出来了，结果根本没人看。
上个月，小王熬了两个通宵，把接口文档写得那叫一个详细。每个参数啥意思、返回值有啥可能、错误码代表什么……洋洋洒洒三千字。
发到群里，心里还美滋滋：这次总没人来烦我了吧。
结果：
十分钟后，产品经理在群里@他："小王，这个接口怎么调啊？"
小王："文档在群里，自己看。"
产品经理："太长了懒得看，你就直接跟我说得了。"
小王：
又过了一周，新来的实习生妹子跑过来："哥，这个 includeDeleted 字段是啥意思呀？"
小王："文档里写了啊，第二节。"
妹子:"看了，没太看懂，你给我讲讲呗。"
小王：
最搞的是上个月，代码改了第八版。
小王翻出当初写的那份文档，自己都看笑了——
参数变了，返回值变了，连接口名都改了。
文档还停留在 v1.0。
默默把文档删了。
"算了，让他们看代码吧。"
程序员的文档，写出来也……挺有风格
程序员写的文档，能分好几种流派。
极简主义派
就这：
用户登录接口参数：username, password返回：成功或失败
看完你只会想问：那……具体怎么调？
装X派
这种文档最喜欢堆术语：
本接口采用基于 JWT 的 token 认证机制，配合 OAuth2.0 授权流程，确保数据传输过程中的完整性和安全性，有效防范中间人攻击、重放攻击等各类安全威胁……
全是中文字，连起来就是不知道在说啥。
代码即文档派
直接甩代码：
# 用户登录deflogin(username, password):# TODO: 实现登录逻辑pass
大哥，这叫文档？这叫占位符。
遗言派
这种最搞：
// 这段代码是XXX写的，我也不知道为啥要这么写，但别删，删了会崩// 如果能看懂，算你牛逼// 当年的我：脑子被门夹了functionfuckThisShit() {// 三百行神奇的代码// 祝你好运}
这不叫文档，这叫忏悔录。
所以，为啥不爱写文档？
说到底，就三个原因。
没爽点
写代码，敲一行，效果立竿见影。
bug 解决的那一刻，多巴胺疯狂分泌，爽到飞起。
写文档呢？
敲一行，啥反应没有。
写完了，也没人跑过来说："牛逼！"
写代码像打游戏，写文档像……填表。
换你，你选哪个？
没成就感
代码写好了，功能上线了，用户用上了，有人夸。
文档写好了，发出去——石沉大海。
这辈子没人会说："文档写得真好！看完了立刻就懂了！"
没尽头
代码有版本号，文档没有。
代码改了十版，文档还停留在 v1.0。
最后索性不写了——反正写完也得改，不如不写。
但说真的，文档这事儿，得写
话虽这么说，文档该写还是得写。
为啥？
文档写得好，团队少烦恼。
新人上手快，不用天天追着老员工问。
接口对接顺，不会因为字段对不上扯皮。
你自己也省事，三个月后不用对着自己的代码发呆。
团队效率高，省下来的时间可以写更多代码。
记住一句话：写文档不是给别人看的，是给三个月后的自己看的。
到时候你会感谢当初那个"不情愿但还是写了"的自己。
那咋办？有没有办法让写文档不那么痛苦？
有，分享几个实用的。
边写代码边写文档
别等代码写完了再补文档，那样你根本不想动。
写接口的时候，顺手把参数说明写了。
写函数的时候，顺手把功能描述写了。
就像写注释一样，自然就写了。
用工具自动生成
Swagger、JSDoc、Docstring……这些工具了解一下。
代码写好了，文档自动生成。
虽然生成的文档可能不够友好，但好歹有个基础，稍微改改就能用。
简单粗暴，别整花里胡哨
文档不是写论文，不需要那么多专业术语。
就写四点：
这四点写清楚，就是好文档。
别整什么"基于xxx架构""采用xxx模式"，没人爱看。
用例子代替说明
// 请求示例{"username":"test","password":"123456"}// 返回示例{"code":200,"msg":"登录成功","data":{"token":"xxxxx"}}
一个例子，顶十句说明。
最后说两句
程序员不爱写文档，这事儿挺正常的。
写代码是创造，写文档是总结。
创造有趣，总结无聊。
但文档这玩意儿，就像体检报告——你不想看，但关键时刻能救命。
所以，该写还是得写。
你也不想三个月后，对着自己的代码怀疑人生吧？
来评论区聊聊：
你见过最离谱的文档/注释是啥？👇
我先来："这个函数的具体原理，我也不懂，但别删，删了会崩。"
纯属娱乐，如有雷同，咱们都是一条绳上的蚂蚱。
#程序员 #文档 #代码注释 #技术生活 #程序员的日常
