最近公司项目的调用量突然涨了一大波，很多系统都纷纷扛不住了，于是需要对系统进行优化，系统优化的第一步，便是梳理业务！在这个过程中，经常出现了这样一些情况，发现数据库的某些字段，没有注释，也没有一定的文档来诠释它做什么作用。而这个项目又是多达20，30人一起开发维护的，没有人能够从头到尾说得清这个项目的主要流程。写文档，似乎在国内的程序员，最不屑的一件事情了。作为一个程序员，有没有必要写技术文档呢？
image.png
要不要写文档
我们常说，Talkischeap，showmeyourcode。但是在实际的工作开发中，绝大部分情况，code才是最便宜的。工作的大部分时间，都是在进行业务的梳理，接口的沟通，剩下的，才是代码的编写与测试交付。有些人会说，写文档是让老板跟容易找人替代你，也许现实生活中存在这样的情况，但是一个人能否被替代，更多的是自己有没有核心竞争力，每一个互联网产品，都是有生命周期的，如果你的核心竞争力就是掌握了现有系统的坑，还不如提升自我，让自己到哪都有饭吃！也有人会说，写文档是写给老板们看的，对提升技术并没有多大的作用。这句话只是说对了一般，最近，我们有一项重要的项目要对客户与上面的老板进行汇报，再一次感受到会说话的重要性，对一些不太懂技术的人说技术，是一门学问。写代码，终究只是人与机器交流，而写文档，是人与人之间的交流，大部分程序员，都不可一辈子在单打独斗地写代码，学会与人交流，决定了你的上限。也有人说，只有大公司才写文档，小公司，做的都是一次性的项目，写了文档又有什么用。写文档，其实并不是完全是写给别人看，更多的是，让你去进一步了解业务，了解技术，对业务进行梳理，站在一个更高的角度去思考整个系统。我有一个朋友，一开始只是一个外包公司的开发，但他非常擅于进行业务梳理，很快，他也自己出来开了一个外包公司，也过上奔小康的生活。
那么，如何写文档才能避免写流水账呢？怎么样写文档才能让所有的人都看懂。个人觉得，写文档最少要写两方面，一是总体设计，二是详细的技术方案。
总体设计文档
首先是需求与功能，用自然语言来描述这个系统要实现什么功能，有什么作用。经常有程序员想找挣外快的机会，可是连自己做的东西有什么用都说不清的，真的很难去合作或者谈到更高的价钱。其次是架构与系统模块。这个系统涉及到哪些功能模块，每个模块之间的调用关系是什么样，最好有一个简单的架构图。最后是一些方案的对比，我们常常被教育着去寻找标准答案，但是这个世界更多的是合适的方案。多思考一下有没有其他的方案，为什么最终选择这个方案，下次做到类似的需求，相信你会受益匪浅。
详细设计
详细设计，最重要的就是数据结构。这个功能主要有哪些数据，数据在计算机内部是以什么形式进行存储，表如何设计，这些都是至关重要。多年的写代码经验告诉我，一个系统如果常出问题，无论是业务问题还是性能问题，绝大部分原因都是因为数据结构没搞好。所以，在一些大型的公司，架构师的首要职责，便是梳理好基础的数据结构。系统调用时序图，也就是交互流程，一个请求从一个系统流转到另外一个系统，顺序是什么样，各个系统又完成怎么样的责任，建议用时序图进行表达。性能指标与可拓展性，最后，如何跳出当前的业务去思考整个一个系统，当前的系统如何去应对将来的业务拓展，如果流量增加性能瓶颈又在哪里。好的设计不是一蹴而就的，而是不停地进行思考和迭代。
总结
程序员到底该不该写技术文档，相信你已经有答案。就好比盖房子，即使不用设计图，你也可以一边搬砖一边盖楼，但是，如果你想盖一个地标，一个摩天大楼，只有先有图纸，才能预估好整个大楼的空间、承重、稳定性。另一方面来说，当你拥有了图纸，拥有了画图的能力，盖房子不就是找一群建筑工的事情么？写代码亦是如此。好了，今天我们就介绍道这里，欢迎大家