程序员们，大家喜欢写文档吗？

[liyiming2002]

文档之于程序员，是很矛盾的事情。程序员非常不喜欢写文档，但又非常讨厌别的程序员不写文档。

朋友们可以关注下我的个站：www.icodebook.com

公众号：漫话软件设计。

《漫画程序员涛哥》会在公众号及个站第一时间更新。欢迎大家关注~

往期漫画：

《改个 Bug 要多久？大家有没有过于乐观被打脸的经历》

《程序员错觉之出差下周就回来》

《假如让程序员去换灯泡》

〈程序员错觉之这个需求两天搞定》

我觉得推崇“代码即文档”外，一些必要的设计文档也是必不可少的。另外也不能完全迷信代码的文档能力，这需要较高的水平和经验。一些关键业务的代码可能也需要配以文档。但文档不宜过细，否则需要频繁改动，但是无人维护就会过时。

[edisonwong]

写文档我排期排一天，我能 2h 写完。就是评审的时候，提一堆无关紧要问题，明明文档里有写，突出一个参与感... 以前噼里啪啦快敲一顿文字，现在画流程图、架构图各种图画得不亦乐乎，用图说话，有好的技术建议也很欢迎，不仅自己思路开阔，还能继续回去改，继续占 pd

[edisonwong]

如果不给时间或者压缩我开发时间，那只能随便写，尽可能少暴露细节。。不然又引起一堆无谓争议，来回开会拉扯

[xiangbohua]

说实话，我还挺喜欢写文档的，比如说方法的注释，我喜欢把方法的注释写的很清楚，比如参数怎么传、要注意什么、返回值含义是什么、是不是允许空之类的。
当然，设计文档的话，我写的比较少，主要是不太会整理格式，

[xiangbohua]

看到还有一句话，代码及文档的，我也是比较喜欢推崇这个。功能的实现我喜欢个方面控制的比较死，尽量保证实现的人只要按照接口要求实现就不会出什么问题的这种，但是感觉文档还是需要写的。

[xiangbohua]

@opengps 对对对，特别是一些方法，明明就是 getEntity 非要写一个“获取数据库实例”这种就觉得没有必要

[Otho]

不喜欢，但是尽量写

[liyiming2002]

@honmaple 你的情况属于主次颠倒了。。。。。。代码写的漂亮基本不用非常详细的文档。不过概要设计文档、架构文档我感觉还是需要的

[liyiming2002]

@csw3983931 漫画是我用 ipad 画的。以后不知道是不是可以 ai 做了，哈哈！

[liyiming2002]

@edisonwong 如果不给时间，那就是白嫖文档。坚决抵制！

[746970179]

文档不了解, 但是注释有点个人见解

不要写代码做了什么( 不要去翻译代码 )
而是写我要做什么( 结合业务, 说明想实现的逻辑 )

比如 python 的一段代码, a_set & b_set
不要写 找出 a_set 和 b_set 的交集, 或者 找出 a_set 和 b_set 的重复数据
而是结合业务, 写 两个店铺都出单的产品

[liyiming2002]

@746970179 代码能看懂的不用写注释。能用代码代替注释的尽量通过代码的结构和命名来代替注释。