关于写文档和写代码的问题，大家觉得如何协调解决才好？
　

---

很多时候，我们在项目越来越大的情况下，感觉到我们需要一些文档来辅助，但是每当要写文档的时候，却总是觉得力不从心。不是没有时间，就是来不及。或者，转身一思考问题，就把文档给忘了。
文档到底重要不重要？
在赶一个工程的时候，上面的曾经做过技术多年的一位老大总是在催促我，尽快进入编码阶段，尽快进入！每次见我，都问我：什么时间开始编码。
——我，那时候，在尽量促使大家对业务更理解一些，把需求分析得更详细一些，尽可能的做出一些设计来，但是，因为这个，我让整个团队在前两个月内都没有进入编码阶段，后来在这位老大的催促下，提前了两个星期开始了编码工作，但是，在这样赶工期的方式下，文档最终再次被舍弃了。虽然前期文档的编写，让大家对需求了解得更详细了，让大家后续的工作进展得比原来顺利多了。可是，这些文档，随着后续的需求变动，现在基本上都已经作废了。
想来，真的是一种遗憾，也是一种无奈。不过，如果按照现状继续走下去，将面临着一系列后续维护的问题，维护和系统的升级都将出现非常严重的麻烦。
各位有没有什么更好的意见来解决这个问题？

 回复: 关于写文档和写代码的问题，大家觉得如何协调解决才好？
　

---

我现在倾向于xp
太多的文档意义不大，我带几个人也这么做过，一段时间没结果，大家激情都没
了
　

调研需求阶段：
这个阶段就是尽可能全面地记录用户提出的显性需求。
系统分析阶段：
这个阶段是对调研结果，也就是用户的显性需求的总结，写出文档；同时还要对一些隐性的需求凭过去的经验、通过分析归纳出来。按照正常的软件工程过程，需求文档一定要写得很详细很详细（当然如果是采用原型化的开发方法就得另当别论了）。但是有时候考虑到时间问题，我们必须有所取舍。我采用的方法一般是简化需求的书写量，对一些客户明确提出的功能性需求，我用少量的语言提及一下。但对一些模糊的需求，还是认真地总结，还和客户进行讨论，再情况修改文档。 对于隐性需求（一般是系统功能，如安全性、可维护性、运行效率等，不是客户所要求的业务功能），如果时间允许的话，我就会给予强调说明；上头在催了，我就简要提及一下了。
系统设计阶段：
这个阶段是直接为后续编码服务的，我的设计原则是结合具体的开发环境进行设计（我用的是MFC&ATL）。假如时间允许的话，我会给出全部的类中的操作的流程。如果项目需要速度，那只能放弃质量了，我做法是对一些简单的实现过程我就不做出详细设计了。对一些核心模块，我还是会给出详细的实现过程。

说明：
我做分析和设计的时候基本没有遵循一些软件过程的方法。像我做设计的时候，就没有概要设计和详细设计之分。做好分析之后，就直接对类进行扩展了。青润老兄，你是分析和设计方面的高手，有很丰富的实践经验，希望你能多指导啊。

 但是，没有文档，就说明我们仍然处于手工作坊的方式，编写过程也是师傅带徒弟的方式，
　

---

这不利于进行较大规模的软件开发，三五个人还可以，如果能力更强，十个人也许问题不大，但是，如果项目的规模再大一些呢？十五个人，二十个人该怎么办？如果有人跳槽走了该怎么办？
单靠人的大脑来记忆，这是非常不合适的。

 不敢当，不敢当。我也不是什么老师，只是过来和大家讨论讨论问题而已。不过，你的描述中有一些问题存在。
　

---

由于你的描述比较笼统，只讲了很传统的需求过程，这种方式实际上在现在已经很不能适应新的工程过程了。当然，如果非要这样执行也并无不可。
我对于你的描述有几个问题要提出来，如果这几个问题都可以很好的解决，我想应该可以比较好的实现这些过程了：
第一、如何全面记录显性需求？你对显性需求的定义是什么？你的需求是如何划分的？需求阶段应该做哪些工作？
其实每个做需求的人在自己的脑海里面对需求都有一个分类定义，都有一个划分方式，这些方式不尽相同，我的划分方式就和你的不太一样。
你的所谓的需求过程实际上在我的需求划分中只是需求工程的前半个部分，只是需求调研阶段，或者说是进行需求的收集工作的过程。
第二、需求调研工作是一个很持久的工作，需求也不可能一次调研清楚的，所以，会不断的有一些变化，一些是我们对需求理解的变化，另外一些是用户对自己要求的变更。你如何来应对这些问题，如何来适当的解决，如何让用户认可你的拒绝——尤其是这个问题是最难以解决的，有些用户的态度很强硬，有些则比较容易说话。
第三、文档如何才算是详细？如何简化？
第四、你有没有考虑采用模型的方式来取代大量的文字描述？
第五、系统架构如何构建？
第六、系统架构如何对应业务逻辑的具体实现，界面逻辑如何与业务逻辑对应？
第七、解决了系统实现架构，那么系统的性能如何提高？如何解决一些性能瓶颈的问题？
第八、你如何绘制类的操作流程？类间关系尤其是互动性关系如何表述？
第九、模块的内聚性如何调整？
第十、什么时候才是时间不够，时间不够了，如何做出让用户满意的产品？如何调整用户对系统的新的要求？

以上是你的内容中需要提到的十个问题。
关于概要设计和详细设计的问题，我现在采用的是Uml建模的方式，借用RUP中关于分析模型和设计模型的过渡方式实现的。分析模型可以让用户中的高级用户看懂，因为其流程和内容都是中文化的描述，还没有具体到类的设计实现，只是一个对类的详细分析。设计模型中会将分析类全部转换成设计类，然后对类进行详细的设置，同时绘制出各种时序图来表述类间关系。我现在还在继续这样的试验。

 回复: 青润老兄
　

---

青润老兄：
我的分析与设计水平有待提高，还有很多知识需要学习。你真是厉害，以后多多地向你学习。后天我要考系分，现在要准备准备。以后多多向你学习。
谢谢你对我的回复提出的十个问题。

看了你们的讨论,表示理解。
qingrun，你的那种开发模型真把我们这些小团队吓着了。
对于需求的进化，如果把握住商业合同，应能避免掉大部分后期的伤精动骨，在项目管理中，界定系统边界能依据合同（用户签字）容易找到判定原则。
需求在开发阶段，重要点是多方共享。比如对一电子政务系统，不可能有精确需求（犹如计算数学与分析数学的差异），但多方却应该尽量有共同认识点。确实以纯文档很容易歧义，而模型语言会有更好的效果，但对大家的要求就高多了，实施成本上升，对小项目、小公司，只有羡慕你们的份了。用原型法，对我们小项目、小公司应该好些吧？但实施时也不顺利。至于文档资料与代码的同步，你的UML回容易些，我门能在后期补充主要的文档资料，我就很感谢老天了。
另外，个人人为，XP方法适当修改，应该可以用于“大项目”。

对用户业务过程的描述就是业务文档。
对软件系统过程的描述就是软件文档。

这里我们主要来讨论软件文档。
只有运行程序不是软件文档。
源代码是软件文档；
源代码说明是软件文档；
设计模型是文档；
测试设计是文档；
分析模型是文档；
需求规格说明是文档；

什么文档是最不可省略的？
除了源代码，其他文档都是可能可以被省略的，所以源代码这种文档是最重要的。谁说程序员不写文档？他们写的是最重要的文档。

文档有什么用？
得到运行程序。各种文档只不过是离运行程序的距离越来越近，也就是离计算机的理解能力越来越近，离用户的理解能力越来越远的，对同一个产品使用不同语言符号所作的不同描述而已。[有意思的是从源程序这种文档到运行程序的过程已经完全能自动化地完成（编译），这种转变却实现了从用户最难理解的形式到最容易理解的形式的跨越。]
我们看看在这个文档版本变换过程中使用的都是那些语言？
需求规格说明，大致使用的是自然语言；
分析模型，使用分析语言；
设计模型，使用设计语言；
实现模型，使用编程语言。
其中分析语言和设计语言可以同时用UML，但用法和技巧稍有不同。
无疑，不管是用那种语言，读应该对要实现的产品有尽可能清晰明确的，而且相互一致的描述。
要做到这一点容易吗？不容易，为什么？最难的是什么？
从语言的掌握程度来看（这里谈到的对语言的熟悉包括熟练运用表达思想，不仅仅是理解语言符号的含义）：
用户最熟悉的是自然语言，最不熟悉编程语言。
合格的分析设计员对所有语言都应该熟悉，问题是有大量的不合格的分析设计员，他们可能至少不熟悉其中一种语言，甚至是自然语言；
程序员特别是高手最熟悉的是编程语言，甚至超过对自然语言的熟悉程度（不要笑，是真的，如果今天有人推出自然语言编程的开发工具，使用最困难的人一定是程序员）。
大家各自用自己熟悉的语言来描述未来的产品，于是出来各种文档。如果要求不同的人用它不熟悉的语言去读或写文档，就会带来难度。
由于有自然语言可以让程序员和用户直接沟通，所以，最容易被省略和最容易尚失作用的是分析设计语，这是自然的。
然而，最难的不是表达思想，而是思想本身。语言符号不会给人带来多少思想，只有更多的知识、更多的实践、更多的总结，才给人带来思想。试想，如果一个没有思想的角色，无论他用什么语言写出来的什么文档，那一定是垃圾。有的程序员虽然不懂分析设计语言，但很会思想，有的分析设计员虽然懂UML,但不会思想。会思想的程序员的代码本身就是极佳的文档，不会带来任何维护问题，他也能看懂大部分的代码形式的文档。在中国，至少自认为是这种程序员的不少，所以，造成分析设计文档无效的现象比较普遍。

到底要不要写文档？
要看由什么人来写什么样的文档。
　

 实际上也没有那么严重，只是在遇到具体问题的时候需要具体分析，我根据他的描述才提出了这么十个问题，如果在深化，我想应该还会有一些问题的。
　

---

其实很多项目都是类似的，就象你所说的：“不可能有精确需求（犹如计算数学与分析数学的差异），但多方却应该尽量有共同认识点。”
有些时候这个共同的认识点是很麻烦的事情，只有当用户方负责人对软件比较熟悉的时候才可能比较好定义也比较好共同遵守。但是，大多数用户方的负责人都不是这样的，所以，我们的任务还很艰巨，不仅仅要提高自己，还要考虑用户方负责人有哪些可能的考虑，以便于应对呀。