程序员是否该写文档？

不论是需求的原型，测试使用的TestCase，离职时候的交接文档，个人的学习笔记，或者是怕忘记做的备忘录，这些都算是文档，你有写文档的习惯吗？

甲：要求写的时候写，不要求写的时候懒得写

乙：有时候记点儿东西，脑子记不住，一般用有道云笔记记录一下

丙：有，离职的时候这些，必须要求写的

……



如果你写过文档，或者有写文档的习惯，你上一次写是什么时候？距离现在有多长时间了？

甲：刚刚才写的，刚刚过来开会的时候，手头的那些记下来

乙：好久了吧，现在写的看起来像流水一样，不像文档

丙：不写文档……

……



你现在还写文档吗？如果现在写的少了或者已经不再写了，是为什么呢？是时间不够，手头活太多了还是？

多人：活太多了……（附议中）

甲：没时间感觉，一天到晚在忙

乙：没有写的习惯

丙：写了用不上，需求改了文档懒得改

……



其实，我也不喜欢写文档



没时间，每个周期每个Sprint大家手上的活儿有多少，什么时候开完测试完成都摆在那里。先不说是否能在规定的时间内高质量的开发/测试完，如期上线，这些已经很占用时间了，再加上分配Task的时候，除去测试以外，也没有将文档算在开发任务里，没有给相应的时间。所以最大的原因是时间不够，哪怕是有写文档习惯的人，慢慢的也就不再写了。



就像刚刚说到的，布置分配Task的时候，没有规定完成是否需要有相关的文档，只要能见到代码，能看到功能正常就行了。确实，事实上很多时候连代码的质量都无法保证，没有花时间去Review和重构，又哪会去写文档。不管是重构Code还是写文档，在很多公司里，没有规定和要求，本质是一种期盼，说白了，能做到最好，做不到也没什么……如果做了，那属于额外的工作量。

额外的工作量是容易被忽视的东西，不会直接带来收益



当时《甄嬛传》很火，应该不少人看过吧。对这幅图应该熟悉，当时扮演皇后的蔡少芬说：臣妾做不到啊。有的人说自己不擅长，不会写。这也确实是，不管什么事，做的少，大多数的人自然而然会失去做的勇气



哈利波特可是当年风靡全球，当时波特还是小鲜肉，再看10年后，满脸的络腮胡子，10年的变化真大。

我们这一行，坐的时间长，想减肥的人不在少数，明知道坚持下去，会瘦，不一定帅，但身体素质会提高，但是做到比较难，为什么，因为短期内看不到效果。

我们写代码，写几行，可以运行F5调试，看到那几行代码运行的结果，写的对不对，是不是我们想要的结果一下子就能看出来，这种结果获取的速度很快。

如果是写文档呢？一笔一划的写完，没有直接的刺激，在生理上，属于一种慢速反馈，没有那种享受和刺激，尤其是在现在这个快餐时代，追求的是快，快，快，所以这也是一种不愿意写文档的原因



乔布斯当时最伟大的发明是什么，iPone4的诞生，抛弃全键盘，改成一个按键，大胆的创新，他成功了。时隔现在iPhoneX都出现，还加了齐刘海。现在一个用户不一定喜欢iPhoneX，但肯定也不会去买一个iPhone4或者4Pluse。为什么，过时了，就像现在出门也没人用BB机、大哥大，消费也不带着现金一样，过时了。

写测试用例是最有代表性的，有的公司TestCase是和开发并行的，写了N多，需求一改，势必很多会改。这还只是即时性问题。当时需要这份TestCase，写到最好，但后续的开发周期里，同一个模块、功能变化，当初的文档参考价值就会降低，甚至是过时。开发文档这些都是一样，事物的本质是在变化的。

但花费了精力、心思和时间写的东西，会过时，次数多了，慢慢也会产生“反正会变，写了也会过时”的想法，那必然也就不愿意写了。



刚刚，我们讨论到不愿意写文档的几种原因。事实上，也有很多人在写着文档。我曾经看过一篇文章，程序员75%的时间是在写文档，先不论这个行为是否对错，也不论是否真的有公司或者开发者这样做的，但至少存在着很多愿意写文档的开发人员，我们分析一下他们的原因，为什么愿意写。



图中，一个男孩，手里捧着肉丝，单膝跪地，旁边放着一个礼物，面对着一个女孩，应该是在表白或者求婚，你们说这个会成功吗？

甲：不会，这个男的没车，没房……

已：不会……

你们还真是…..，我也不知道这个男孩会不会成功。这个女孩想要的是不是这些浪漫，这些我们不知道，所谓知己知彼，百战不殆。

我们开发一个功能，有的时候，逻辑复杂。Jira上也没写的让你非常清楚，你问了不及时记录，也会忘记，这都是经常遇到的事情吧。甚至记得不详细，还是不知道流程，越是这样，开发的时候也会越没底的。

如果一边写着文档，就像提纲一样，1，2，3……这样的，然后下面开发。开发的时候遇到细节再补充到文档里。写完一个模块，能验证有没有疏漏，是不是产品想要的东西。这个我有亲身体会，这样磨刀不误砍柴工，返工次数会少。



这个和上一点有些类似，也可以理解为上一点延续出来的产物。开发遇到的细节，补充到文档。整体一个模块开发完毕，在对照着文档检查一遍，看看代码和文档是否一致。

毕竟没有谁想让自己的代码Bug百出，有些对自己开发的质量高要求的人，这一步尤其看重。也许你会说，不是还有测试吗？但是细节真正清楚的是你，你比产品、测试、项目经理都清楚。



这个是我加上的一点。说来有些小人了，想做到有迹可查，如果出了功能不对的问题，不是bug一类，是功能和想要的不一样。我们来看看最后一次文档就是这样的，是校验过的，有变动的话，是什么时候和我沟通的。当然了，我们的共同目的是以解决问题为主。



这个游戏不是LOL，是现在火热的王者荣耀。都是5V5的，除非是青铜分段的，否则一个亚瑟或者盖伦不可能1V5拯救世界的。还是要打团的，这不是一个人的游戏，需要配合的。

在今天这个分享前，Neo和我商量前后端接口，我直接发过去我的文档，回复我的是6个字，分2行。第一行是“很清楚”，第二行是“很方便”。在前几天和求哥晚上加班，他问我接口，我直接发给他我的文档，他说你们现在开发都这么规范了吗？就应该这样做，很清楚。

现在都是前后端分离的模式在开发，需要多个人配合。就靠口头说或者写草书，在我见到的，没有记忆力好的，一遍商量就可以不再重复讨论的。重复讨论不是因为接口少东西，而是这个字段的类型忘了，那个字段的名字不记得了。这种事情双方都烦，但是和那两位同事合作的时候，一遍搞定，除非是接口少了些东西。



我在分享前，在网上找到一个写文档的好处，可以称之为“至高境界”，和大家分享一下。有经验的开发人员流失造成开发低水平循环，开发经验无法继承。

这里有经验的指的不仅仅是开发人员、同样产品也是，测试也是。

我刚来的时候，哪都不熟，产品产品不熟悉，功能功能不熟悉，开发的时候表不知道是哪个表，字段不知道是哪个字段，但是需要直接上手的，那怎么办，文档没有，问呗。口口相传。那时候问军哥多一些，后来军哥离职后，还在问他。因为没有文档，甚至有些问题反复的问，毕竟业务不熟悉不同，名词也不清楚。熟悉的过程是必须的，但是内耗的时间肯定是大于了熟悉需要的时间。

程序员有个现状，大多数的还是属于那种shy类型的，不愿意开口问，尤其是初级或者刚入行的，他们消耗的时间肯定更多。实际我还是崇尚那种办公环境，有什么，扯开嗓子问一声，唉，那个谁，那个XX是哪个字段来着……扯远了。

这种站在公司利益角度上思考，确实境界更高。



还有一种低级的境界，是我的境界。代码是可能会删除的，会更新的。如果有一天，如果我离开了一个公司，但至少这个公司还保留着我的痕迹，这是让我开心的事情。



程序员应不应该写文档，这种问题是个辩论题，用于辩论的问题就是没有所谓的对和错之说，就像开发语言哪个好一样。不是说写文档一定是好事，不是说不写文档就是差劲的，这还是得看自己的风格和对自我的要求还有实际情况。

谢谢大家