从零开始编写本身的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/