进入普元primeton.com三个多月了，主要在做文档生成，不过经历了一些折磨，也加过两天班，有一些体会，有一些教训。
    以下就是一些个人对这段时间工作的一些思考和对软件工程管理的一些看法，也可以算是一次总结。


摘要

    实现文档生成的过程中，自己无意中多添加了一些不必要的功能点，整体进度有所拖后。到了后面快结束时，逐渐意识到文档生成需求文档的不足和缺陷可能是问题\r 的关键。最后总结认识到做软件需要对需求进行科学的定制，要评审需求，并通过总体设计和详细设计来反复评定需求，确定最终功能点，不要在编码实现过程中添\r 加需求外的功能点，测试应该建立在需求而不是实现上。
    教训：除了重视需求外，还是要重视需求。


初期的两个错误以及事后诸葛亮

    从蔡静那里接手文档生成项目的时候，我是很快就明白了个中实现原理，反正是不难，不过我一开始就犯了个根本性错误：不重新设计，就直接使用蔡静原有的框\r 架。这个错误导致了最后各种各样的问题。一开始的时候，我向张利强要了文档生成的需求文档，那个时候看了一下，没看出什么来着。不过现在回头想想，其实， 那一份需求文档实际上，说不上是真正的需求，都是从技术角度出发，有点总体设计的味道了。而且说的都是界面上的东西，真正文档生成的内容如何，生成的文档 是给谁看的，文档的格式如何，都没有说，或者是在界面上带过而已。由于一开始的时候，我根本就不去实现涉及界面相关的功能，所以我也就不去看这些需求文 档。不看不研究这些需求的文档的结果，就是做出来的东西最后变样了。就现在而言，我应该在那个时候好好研究一下需求文档，进而发现前面所说的需求缺漏，从 而自己再做一份详细的需求文档，提交到产品管理部，重新评审需求。在重新写的这份需求中，则应该把原有需求文档中的界面等东西，转入到总体设计中去。从而\r 在我在慎重考虑总体设计，并结合评审后的需求作详细设计，有了详细设计之后抛弃蔡静原有的框架，进而重新写一个框架，使得文档生成有更高的可扩展性和可维 护性。不过这些只是一个幻想了，有点事后诸葛亮的味道了。


多实现的功能点

    前面已经说了，我在开始接手项目的时候，就有了两个致命的错误，所以后面的就出现了很多的问题。首先我做的是针对PDF的文档进行结构设计，也就是使得生\r 成出来的文档像其他文档一样，有页眉，有脚注，有封面，有目录，有书签，有摘要，有总结，有生成器版权相关信息，这花了我一段时间，进而在加入一些常用的 构件的文档信息，有统计信息，有标准构件库的构件的信息。但是就现在回顾而言，其实就实用性而言，生成的文档并不需要页眉，不需要封面，不需要文档摘要， 不需要总结，不需要生成器版权相关信息，统计信息意义不大，另外标准构件库的构件信息也有其他专门的文档了，不需要重新生成。所以这些功能都成了额外的负 担，这一直在消耗我的时间。到了现在，在PDF文档中还有的是：页眉、脚注、书签、摘要、总结、统计信息，其实就实用和简洁而言，页眉、摘要、总结是应该 去掉的。也就是说最后文档结构只有脚注（页数）、书签（导航）、项目资源的信息、项目统计信息。从最实用的角度和我曾经设计文档结构相比较，就可以看出我 由于缺乏科学的需求文档而浪费的时间是多么的长。其实在我实现的初期，我就考虑了生成的文档的多语言支持问题，这个在需求中没有出现，可是我却实现了，这\r 是因为原来我也曾经设计实现过具有同样多语言（中文和英文）的表格工具，所以我在初期稍微改动点就实现了这个功能，可是到了最后这个功能却被我屏蔽了，因\r 为什么呢，我觉得其实就目前的用户而言，根本没有中文版本以外的需求，这也是需求文档中没有明确用户所导致的错误。也许初期我的实现多语言版本没有太多的 困难，可是这个在我后面的开发过程中，却一直在或多或少地消耗着我的时间资源。另外就是前面说到的存在摘要和总结之类的结果，导致我要在界面上允许对这些 信息进行设定，这也就耗费着我的时间资源。


文档格式的需求不足

    其实，在我拿到的需求文档中，还有一个HTML的demo文档，由于HTML的文档和PDF、RTF文档有着不同的格式，从而使得HTML的demo在我 设计PDF、RTF文档的时候没起太多的参考作用，从而前面说到的文档结构的东西都是我凭空给实现出来了。说到HTML文档，我最后选择的是直接和 PDF、RTF文档生成采用由同一个XSL FO文档来生成，也就是HTML文档中所有的元素的布局和信息和PDF、RTF文档是一样的，这样设计是为了开发和维护变得相对简单，事实上证明了我这样\r 设计其实是对的。但是由同一个FO文档出来的HTML文档是单独一个文档，这与demo中的多个HTML不一样，于是我就把这个单一的HTML进行拆分， 之后得到类似的多个文档。然而这样的HTML文档最后并没有采用，而是最后有一个需求添加，也就是在HTML文档中使用类似JavaDoc的形式用框架来 显示，并在左面的框架中使用类似PDF的书签的树状结构来导航。其实“使用类似JavaDoc的形式”在原始的需求文档是有描述的，但是毕竟人家 JavaDoc的形式也是很多的，也是很完备的，不是“类似”两个字能够表述的，从而我觉得至少要用比较多的详细设计来代替需求中的“类似”二字。而且由 于要生成的项目是EOS项目，和Java的项目不太一样，也需要进行详尽的探讨才可以做到“类似”二字。HTML文档所带来的问题，和前面说的PDF的问 题，也足以说明在需求上并没有太多的说明。或者说缺乏详细设计。
    前面说到的PDF、RTF、HTML等格式的文档，其实原始需求中还有一个XML格式文档的需求，其实从蔡静接手过来的框架确实已经存在一个\r data.xml的中间文档，但是这个中间文档的格式可谓是横七竖八啊。我居然遇佛拜佛逢魔杀魔也不管data.xml的中文档如何，一律给当作临时中介\r 来用，对于小项目也没有什么问题。但是到了一定的时候，这个data.xml的问题就出来了。当然这个不仅是data.xml的问题，更多是整体性能的问 题。这个起因是文档生成需要对大项目进行文档生成（譬如5000多个资源文件的项目），这就是使得data.xml异常的大，以至于整个文档生成中使用的 xslt技术无法进行，而是使得不得不重新考虑data.xml的设计问题。然而在讨论data.xml如何更改来适应大项目需求的时候，就发现了这个\r data.xml的所谓XML格式文档的存在必要性问题。因为本来大部分的EOS项目资源文件就是XML文件，data.xml只不过作为这些XML文件 的一个堆砌而已。后来对于如何生成大项目文档，采用的技术手段可以按照分project或package的方式进行分步处理，从而使得xslt技术可以进\r 行下去。而data.xml就不再有存在的必要性了，最后我们采用了所谓的FO文档作为XML格式文档，但是实际上我并没有可以地去实现这个FO的XML 文档，界面上也没有选择XML文档的选项，因为没有人会真正去用这个文档。也就是说原始需求文档中的XML文档需求是多余。
    其实，所有的工具都是有局限性的，所以前面说到的大项目文档的问题出现就是在我设计实现的初期所没有考虑到的问题，从而也就我加两天班的根本原因。这个局 限性和实用范围其实也是应该在总体设计阶段或者详细设计阶段就应该划定的。也许评审需求的时候，也就应该考虑需求的可行性，从而确定需求是否要去实现这么 个功能点。如果现在需要生成上10万个资源的项目文档，对不起，说不定还得重新修改实现方式。因为目前实现的只是支持千位级别的项目。也就是说规模也应该 在需求文档里面。


功能点实现的优先级

    其实，要控制一个软件的开发进度以及相关质量，则功能点实现的优先级是一个比较关键的因素。在一开始做文档生成的时候，是没有自动机图片生成的，这个功能 到了很后面的才得以实现，也就是说我花了一大段时间在那些后来被证明是实用性不是很大的文档结构的实现细节上，而自动机图片生成的工作却是拖到后面才做， 而且自动机图片生成的工作繁琐度其实也是比较高的，但是由于一些文档生成流程的完整性原因，这个生成的图片质量也就只是可以用的水平。当然后来对于大项目 文档的优化对图片生成也作了很大程度上的改进。同样，对文档内容，对bizlet运算逻辑构件和数据逻辑构件的实现我也是到了最后才完整地实现。然而对于 文档生成这个任务来说，生成的文档才是最重要的，而至于如何生成则是次要的。这样的说来，生成的文档内容没有详细的需求，反而是在届面上如何生成的详细步 骤在需求文档中详细描述，这是一个对功能点的优先级造成了严重错误的影响。另外一个功能点是关于模版的问题，也就是目前的文档生成是可以由模版的修改进而\r 影响生成的文档。但是这个需求一来没有详细说明模版中可以控制那些因素，也没有详细考虑到模版相对于文档生成所带来的投入与回报的问题，也就是，我实现了 一个相对来说比较详细的模版以及对应界面来编辑模版，可是用户根本上就不用这些模版，或者说每一次都是使用默认的模版进行文档生成。这是我做技术开发的最\r 为心痛的事情！所以说模版概念的需求就只是一种技术性的东西，不是目前迫切需要实现的功能，优先级就应该比较低。文档生成的原始需求文档中是没有优先级的 概念的。


需求和测试

    其实目前也进行了一些测试，但是我也是发现一些测试点是除了小部分没有实现外，大部分都是由现在已经实现的功能描述去设定的。但是感觉测试点应该直接由需\r 求来写的，而不是现在已经实现的功能。但是原有的偏重于界面实现的需求能够真正测试什么呢？可能对于studio来说足已，可是文档实用性的测试谁来测试 呢？用户需要的信息是否已经存在在文档中了？。可是用户是谁还说不清楚，需要那些信息也没有详细说明，看来这一层还是没无法做到。也就说不上什么软件质量 的问题了，虽然我们是有软件质量控制的。


代码框架质量

    说到软件质量控制，暂且抛开需求带来的相关质量控制吧。说一下代码质量问题，由于前期缺乏具体文档格式的设计，缺乏详尽需求的说明，以及我一开始没有重新 设计框架，同时经历了大项目文档生成的这个挑战，文档生成的框架已经和原始的框架大相径庭了，而且由于我前期添加了一些可有可无的功能点浪费了时间，以及 原本的deadline的提前，从而带来的加班实现，使得整个代码框架已经相对来说很零乱了。这个零乱也必然会影响以后功能的增加以及相关维护，譬如一个\r 没有在文档需求中说的功能点就是对于以后可能会出现的新的构件资源如何如何通过plugin的扩展点来支持。如果要在现在的框架下实现这个功能点，必然是 要大刀阔斧地进行框架重构的。这也就是最初的需求、最初的设计不足带来的所谓软件的噩梦！


想法和怀疑前的个人说明

    我不太喜欢说话，也不太喜欢随行汇报自己的进度情况，所以很多情况下，小组长或者经理不知道我具体的进度，所以很多情况下有经验的人并不能够及时地对我存在的设计或实现错误进行指导纠正或其他讨论。
    我自己相信自己的实现能力强，也就是说可能会有点技术为上的感觉，但是也知道能够实现并实现了并不一定就说明是好的，有时不去实现某个功能点反而是好的。 实现能力强通常也会多干无用功。而且实现能力强也可能导致自己总是按照自己的想法去实现，从而没有经过讨论没有广泛征求讨论意见，从而可能失去了最优的实 现方案。
    我对功能点的实现的优先级把握也不是很成熟。我对进度的把握有限，这个有可能是因为我犯了技术完美的错误，也就是说我总可以看到完成的功能点里面的不足或者更为琐碎的东西，而完美主义总是不允许这样不足存在。
    我知道自己还是经验不足，也就还是在怀疑的阶段，还没有深入地接触成功的开发流程，所以很多东西只是根据自己的开发经验进行怀疑，进行思索。


一些想法和相关怀疑

    一，想法：需求该如何写，以及谁来写，该如何评审，如何给最后的测试一个依靠呢？
        怀疑：文档生成的需求有没有评审了呢？
    二，想法：总体设计以及详细设计是必不可少的环节，而且最好是能够在实现初期重新评审。
        怀疑：文档生成的总体设计以及详细设计在哪里？总体设计以及详细设计谁来做？该如何实现评审。
    三，想法：总体设计、详细设计、设计审查、编码实现等流程得好好地做，单纯地在没有详细设计前就开始编码是一个绝对错误。
        怀疑：是不是我们研发的每一个人在拿到需求之后，就自主地实现总体设计、详细设计、自己心中的设计审查，然后就是编码实现？而这些流程都没有硬性规定需要 详尽的文档？即使是小组合作开发，又如何保证一些实现能够充分有效地利用多人智慧呢？我们每个阶段的的责人是什么，任务怎样分配的？
    四，想法：在实现过程中不要多加入不必要的功能点，即使是很简单的几行代码；要做到不用加入不必要的功能点，就必须做到必需的功能点是详尽的足够的；不增加功能点是为了保证进度的可控性。
        怀疑：我们在实现的过程中如何评审一些功能点，如果给一些功能点表示不同的优先级，又如何控制功能点的按时完成。
    五，想法：不用去强求什么开发模式，瀑布型开发也好，迭代开发也好，XP也好，其实能够适合特定的环境就是好的开发流程。文档生成就适宜用传统的瀑布型开发。
        怀疑：现在我们的研发是不是从瀑布型转到有特色的迭代型，到现在的其实什么型都不是了？


后记

    本来一开始想回顾文档生成这个任务的实现情况，并思索一下关于功能点在软件开发进度中的实现问题，也就是如何在需求、总体设计、详细设计、编码实现、测试 这一系列过程中对功能点进行控制，使得整个软件开发进度可以控制。原本想法很简单：

    需求：确定所有的功能点，确定功能点的优先级；
    总体设计、详细设计：设计实现所有的功能点的具体方法，并粗略估算实现的所需时间；
    编码实现：注意按照功能点优先级来实现对应的功能点，并不断地反馈功能点的实现与计划的出入，在编码过程中，要注意不要技术性地带入新的功能点，否则新的 功能点给进度控制带来的风险。为了使得不用带入新的功能点，就要求设计阶段能够科学地完整；
    测试：对需求所确定的功能点进行测试，而不是对编码后实现的功能点进行测试。

    关键思想本来是功能点的划分，以及如何保证在实现过程不带入新的功能点的问题。但是我回想我做文档生成的过程，一些问题慢慢地出现，越来越多地可以追根到 需求的不明确，追根到需求的是否科学性的问题，也逐渐领悟到这几个月开发流程存在着许多实际问题，当然有的问题是属于我个人的问题，譬如不及时汇报进度， 也有一些这个开发流程存在的固有问题，譬如，需求的分析和评审问题，从需求到详细设计的断裂，编码实现中的一些重大修正和新的需求增加等问题，但越来越多\r 地，我感觉都是可以追溯到需求的问题上。
    由于可以追溯到需求的问题上，所以写着写着，就大篇幅地对在实际实现过程出现的问题进行剖析和对需求的进行评论，感觉整个的软件开发进度中功能点控制的味道就变了，于是干脆就把这当作是文档生成功能的一次总结吧。
    我对文档生成的这个任务不是满意的，越到后面，随着一些问题的越来越突出越来越严重，感觉到所谓软件噩梦的失望，想想也是时候开始总结其中的经验和更多的 教训了。写着这些东西，倒感觉自己好像是在为自己的一些错误或者不成熟寻找着一些借口，但无论如何，我觉得该是自己的错误就是自己的错误，该是整个开发流\r 程的不足就是不足，大家还都是不成熟的。

多谈点问题，少谈点主义。
聪明的人能够从自己的错误中吸收教训，更聪明的人能够从别人的错误中学到东西。