从零开始编写自己的C#框架（4）——文档编写说明

　　在写本系列的过程中，了解得越多越不知道从哪里做为切入点来写，几乎每个知识点展开来说都可以写成一本书。而自己在写作与文档编写方面来说，还是一个初鸟级别，所以只能从大方面说说，在本框架开发所需的范围内来讲述相关要用到的知识点，至于要更深入的去了解，请大家观看其他大牛的博客或购买书籍来学习。

　　为了加快进度，会对目录进行修改，将一些知识点合并或在后面使用的章节再进行描述。

　　谢谢大家的支持，如果您觉得本文对您有所帮助，请帮忙点击支持或发表评论。

　　在开发的过程中，要编写各种各样的文档，当然也有不少公司根本就没有文档。对于初学者，包括相当多有多年开发经验的人，说起编写文档都会非常抗拒，一讲到写文档很多人都是一个头两个大，不知道怎么编写也懒的写，大多都是能拖就拖，拖不了就草草应付，当然我当年也是其中的一份子o(∩_∩)o

　　为什么很多程序员会很抗拒写文档？

　　这个就不再详细描述，你们问问自己就知道了。

　　本文的主要是想告诉初学者们，为什么我们要写文档，写文档对我们开发有什么帮助，以及对各种文档有个大概的认识。

　　好处一：确认需求，减少程序修改工作量

　　很多朋友都碰到过拍脑袋的老板、客户或领导（说的不好听就是头脑一热，需求不过夜的人），而这些朋友真的是遍体鳞伤，给虐了一遍又一遍，而我也是属于那个被虐的人，呵呵......

　　我以前有位同事，在一起共事时每个项目都要求他写文档，当时他一直都觉得很麻烦，后来换了公司后才真正体会到没文档的苦恼。他的老板是那种很有想法的人，经常会有新点子出来，所以在做项目时，一有新的想法就要求他实现 。而有的想法当时提出后过了一两天就忘了，那么他就杯具了......有次他同我说，现在终于明白文档的重要性了，没有文档的日子都不是人过的。

　　需求的不停变动对于程序员来说，是个永远的痛\(╯^╰)/ ，当然我们也不能坐以待毙，而需求文档就是我们最好的武器（对于那些所有项目都不需要文档的公司不在本文的讨论范围之内）。具体的需求文档编写说明请留意后面的章节。

　　好处二：帮助我们熟悉项目

　　在编写相关文档时，其实就是帮助我们对项目的理解，理顺一些算法思路。

　　没有编写文档时，你经常会想当然，心里觉得已经很了解整个项目结构与需求了，要怎么实现也有了想法，而人的记忆是会遗忘的，等开发一段时间后，原来想要实现的功能可能就忘得一干二净了。而在编写文档的时候，会帮我们认真的考虑整个需求，对一些要求也会详细斟酌，从中发现很多我们没有想到的问题，然后再深入的去考虑怎么解决这些问题，要用什么算法，会不会再引发更多的问题.....文档完成后，整个项目其实就等于在你的大脑里面实现过一次了，在进入开发阶段就会比较顺风顺水，开发效率也会很高效。

　　好处三：提高开发效率，防止出错

　　记得好几年前在一家手机群发、扣费公司上班，当时要开发一个功能，可以在服务器端根据需要控制手机扣费使用渠道、价格...的功能，在接到这个开发需求时，我并不是马上编码，而是花了四五天时间在整理需求，编写对应的开发文档与流程图，由于有完善的开发文档与流程图（具体请看当时的流程设计图），只花了一天时间就完成了主要的业务逻辑，一个2K多行的存储过程（含注释，后来不断的添加新业务最后扩展到3K多行），又花了半天开发出手机端调用程序和服务器端调用接口，而最后测试只花了半天时间，修改了几个小BUG就搞定可以上线了。上线后顶着经常瞬间几K并发量压力，一直运行到公司转型，二年多时间都没有出现过什么问题，为什么这么复杂的逻辑，但开发占用时间很短，测试上线后在大并发的压力下运行都很正常呢？主要的功劳是做足了前期的需求分析与开发文档编写，如果没有的话，嘿嘿......试过的人都知道，你懂的。只有真正了解项目需求，理顺项目流程，并做了深入思考，那么很多常见的问题都可以迎刃而解。

　

　　好处四：控制项目进度

　　如果没有文档，开发一个新项目时所定下的开发周期绝大部分都是很有水份的，有多少能按时完成也是个未知数。

　　而有详细的文档说明、数据库设计、流程图、功能设计都出来后，这时有经验的开发人员绘制甘特图制定的项目开发进度就比较靠谱了。然后开发团队根据开发计划，控制好每天完成的功能进度，一般都能按时完成开发要求，就算有偏差也不会太离谱（除非中间需求变动或制定计划的人经验不足）。

　　好处五：为后期测试工作提供指引

　　有了完善的文档，在进入测试阶段时，就可以根据需求文档与开发文档对功能进行测试，编写测试用例。如果没有文档，都不知道初始功能求要是什么，那只能测已完成的功能、UI等模块了。

　　好处六：为二次开发与软件维护提供支持

　　在上一文中已说过相关例子，没有文档资料、缺少注释，而代码又不规范的话，那就是一个大坑，一个很难填平的黑坑。

　　...... （其他帮助）

　　除了以上好处外，对于初学者来说，能编写一份好文档，并配合相应的成功作品，这将是你职业生涯最好的敲门砖，能提高你自身的价值和应聘成功机率。

　　不是任何时候都需要编写规范的文档
　　当然不是任何项目都需要编写文档的，对于小公司小项目，开发人员只有一两个人的话，为了追求快速出产品，快速上线，特别是有一个好框架的情况下，没有文档也并不是大不了的事情。

　　不同公司有不同的文档编写要求，而格式也是大不相同。对于要求比较规范的大公司，这些文档的编写大都会严格的按软件工程要求的格式来，当然这样做的话没有一定经验，写起来会比较吃力，花的时间也比较长，而当今的网络社会是快鱼吃慢鱼的时代，对于中小公司或个人开发，如果花太多时间的话，那就得不偿失了，所以还是根据具体情况而定，编写的文档格式与要求相应做出调整。

　　对于初学者文档应该怎么编写呢？使用什么模板或格式？

　　在一个项目从开始提出需求到实施结束，这个过程会涉及很多文档的编写，在编写的过程中，对于初学者来说并不好把握，常常会不知道使用什么格式、排版，内容要怎么来写。

　　一般来说通用的模板内容大都内容全面、详细，比较复杂，初学者没有经验写起来会比较吃力。所以编写时可以使用通用模板进行模仿，但不用全部照搬。

　　实际上编写文档就像写作文，只要条理清晰的讲述出相关内容，突出重点，不要偏离该文档主题就可以了。当然如果你能详细的将5个W2H原则说明清楚，再配上相应的图例（流程图），那就更棒了。

　　5个W2H原则说明：1.WHY ——为什么？为什么要这么做？理由何在？原因是什么？2. WHAT——是什么？目的是什么？做什么工作？3. WHERE——何处？在哪里做？从哪里入手？4.WHEN——何时？什么时间完成？什么时机最适宜？5. WHO——谁？由谁来承担？谁来完成？谁负责？6.HOW——怎么做？如何提高效率？如何实施？方法怎样？7. HOW MUCH——多少？做到什么程度？需要多少时间？数量如何？质量水平如何？费用产出如何？

　　不同文档的主题是什么？

　　需求文档主要是为了让实施方了解软件开发完成后要达到的效果，以及和需求方对软件功能进行文档确认。

　　概要设计（总体设计）文档主要是为了和需求方进一步确认需求，以及软件设计的功能是否设置合理。同时也作为后面详细功能设计、数据库设计以及其他相关设计的总体指导，了解开发过程中需要使用的基本算法，以及可能遇到的问题。也方便将详细设计以及相关设计任务进行切分，分配给不同的负责人共同编写，减少花费时间。

　　详细设计文档主要是将总体设计里所讲述的内容进行细化，详细描述所要实现的功能、算法以及流程图。细化到每个页面要放置什么按钮、字段，列表中要显示什么内容，页面要实现什么功能，而实现这些功能可能要使用什么算法等。当写完详细设计后整个项目基本上就出来了。

　　数据库设计是一个很重要的环节，因为好的设计会给整个系统带好良好的性能，为开发过程中减少不必要的代码，提高开发效率有着很重要的帮助。数据库设计是根据详细设计里所描述的内容转换成开发中的数据表与字段。而在进行数据库设计时，常常会发现很多之前没有考虑到的问题，会有很多新的想法与需求，需要添加新的字段，这时在添加的时候必须进行反复斟酌，判断是否是必须添加的，是否必须在第一期开发中实现？能否放在第二期开发？对开发时间有没有影响？影响有多大？因为很多新的想法与扩展都不是必须的，很多想法也需求实现后都没有真正使用到，这样的话就浪费时间。我们必须要按计划与需求来进行开发，而不是随意的添加新的功能进来，这样才能做好开发进度的把控工作。而添加后必须同步更新详细设计文档，补充新添加的字段或功能描述。
　　
　　项目开发计划（甘特图）文档，主要是将详细设计里的每个功能，在实施时进行开发人员，以及开发先后顺序安排，并确认所需时间，制定开发计划。

　　单元测试文档，主要是编写各种测试用例，包括各种极限用例的提交以及返回结果的预期文档，帮助测试人员以及开发人员完善功能设计。

　　部署文档主要是将发布到生产环境的操作步骤以及注意事项进行详细描述，方便相关管理人员能轻松的部署最终上线版本，出现问题时快速找出并解决问题。

　　

　　除了上面所描述的文档外，还有很多各种各样的文档，当然大部分都不是本系列所要涉及的内容，所以暂时就不再深入描述，如果有需要再开单章进行细说。

　　当然实现开发中并不可能很理想化，将上面提到的文档或步骤来实施，而真正的可能是尽可能的压缩你的文档时间（甚至没有文档），压缩你的开发时间，以便能快速产出上线，当然对于小型企业网站或软件来说问题不是很大，而稍微大些的项目，在测试阶段就会非常的头痛了，各种没有考虑到的BUG接踵而来，开始进行扯皮。所以说能规范的话尽量规范，有可能编写文档的话，尽量将文档补齐，这样会减少后期大量的工作，就算有问题进行扯皮的时候，起码有文字性的记载。而对于那些必须的变动要求，那也能让需求方知道你做了多少事情，用了多少工作量，而不是给他们感觉才改了这一点点需求，没什么大不了的，因为需求方大部分人都不知道你码代码时所花费的工作量与付出。

　　相关文档的详细格式与内容，请留意后面的相应章节。
　　

 版权声明：

　　本文由AllEmpty原创并发布于博客园，欢迎转载，未经本人同意必须保留此段声明，且在文章页面明显位置给出原文链接，否则保留追究法律责任的权利。如有问题，可以通过1654937@qq.com 联系我，非常感谢。

　　发表本编内容，只要主为了和大家共同学习共同进步，有兴趣的朋友可以加加Q群：327360708 或Email给我（1654937@qq.com），大家一起探讨。

　　更多内容，敬请观注博客：http://www.cnblogs.com/EmptyFS/