程序员进阶必备--写文档

简单分享一个很实用的在线绘制UML图的工具
https://www.processon.com
对开发、建模有非常大的帮助，可协同在线开发。

写文档的意义

怎样让程序员变得可替代？三个字：写文档。

不愿意写文档的程序员，应该立刻马上毫不犹豫地开掉。程序员工作创造的价值，至少一半是通过文档体现出来才对。

“一个项目换一个人就要让项目大地震一下”，“解决Bug换一个人就不行，因为只有老人知道要改哪一行的哪个关键字”，这不说明这个项目所涉及的技术有多复杂、不说明这个老人是什么技术大牛，而只说明这个项目的项目经理很蠢，这个项目已经失控了。

文档不是事无巨细的流水账，写文档以及组织文档是需要智商的、是需要架构师去设计的。

美国的航天飞机那么复杂，但是在Pilot手里的手册也就那么多，而这个手册可以在航天飞机出问题的时候协助Pilot快速定位绝大多数问题。

不可替代的打工者只有一种：以中高层领导的身份跟完了一个项目，而且这个项目正处于大红大紫的阶段，公司为了防止你跳槽到竞争对手那里，愿意付给你薪水，养着你天天在办公室喝茶。只要项目一直红着，公司就愿意一直养着你。

开发人员的文档的作用

给正在Code的自己看、给几个月后已经忘记这个模块当初是怎么开发的自己看、给要接手自己工作的新人看、给周边有关联开发任务的同事看、给领导等有关人员看，这是产品出bug的时候用来和别人怼的武器。

如果没有文档，这些工作量都会成倍增长。

代码再精简再直观，也不可能有人类语言直观，谁觉得自己厉害到读代码和读人类语言写的文档速度一样快。

简而言之，文档，就像盖楼房的设计图，没有图纸，你是不能开始搬砖的。

领导有没有给你看需求分析文档？有没有拿着需求分析文档给你宣讲你要做什么？没有？不干活。

测试的同事有没有给你看测试用例文档？有没有给你宣讲？没有？不干活。

你自己明白领导的意图了吗？明白测试同事的意图了吗？想明白后，开始想自己要开发的模块里的各个功能模块之间的关系，可以画时序图。

时序图画完了，看看是否有（可能）频繁变化的模块/需求，如果有，请务必使用一些设计模式，如果要用设计模式，请务必画UML类图，如果没有频繁变化的模块/需求，请一定不要用设计模式。

最后，看看在一个功能模块中，有没有逻辑比较复杂的地方，如果有，请画流程图。

模块和模块之间有没有需要明确的协议？如果有，请把协议写出来。

上面这一段话，就是你要写的文档，这个文档的读者主要是你，在你的模块出问题之前，别人通常不会读这个文档（不排除你的领导会要求看你这个文档）。

如果你既不需要时序图又不需要类图又没什么协议需要明确，那么，你就可以不写这个文档。另外，如果这个文档写得好，你的代码是不需要任何注释的。

相关链接：https://www.zhihu.com/question/312019918/answer/608965942