『思考』为什么老外的注释和文档普遍比国人好得多？欢迎讨论

善意的提醒一下，大家都要注意

比喻而已，不用过于计较。

建议先看了《敏捷建模》之后，再来讨论。书里的话，比我在这里三言两句的讲得清楚。

支持！
写出你的设计思路，这样做的考究来。这样提纲挈领的一句话可抵得上上千行的程序。

文档不都是给程序初哥使用的。

多谢晓钢同学的善意提醒，呵呵。XP 当然不是唯一的选择（还有 FDD、ASD、Crystal、Scrum，etc. 你说的 Lean Programmer 的书我也有的。据我所知，Lean 也是敏捷开发方法的一种，发布敏捷宣言的那次重要会议他们也去了。莫非我的大脑内存出了故障记错了？），同样敏捷也并非唯一的选择，甚至有些时候瀑布式开发是最好的选择。不过现在就我们自己的做的大部分项目而言，敏捷确实是最好的开发过程。文档我们当然是有的。Bug Tracking 也是有的，不过可能没有你们那么严格，以后还要多向你学习啊，呵呵。

再次感谢晓钢同学如此宝贵的善意提醒！

曹晓钢
你的批评我完全不接受，并不是我混淆了那个概念，而是我经常看到的一些人混淆了那个概念。其次对于你的关于UML来自数据流图的说法你还是回去看看方法论大战的历史沿革比较好，当然这个问题和我们讨厌的主题无关。
你说：albert_qhd的这个说法我是赞成的。文档工作的目的，是为了在整个项目的开发周期中，能够跟踪到原始的信息，能够有迹可循。
这很好！但是我不知道你怎么保持这种可跟踪性，你是依靠手工还是依靠什么工具。代码和问题的同步问题是一个至今依然没有解决的根本性困难，你不要说你自己找到了什么仙丹妙药。
同时请你注意不要混淆文档和档案的差别，我不想和你讨论档案。而对于变化，关键的不是要记录和要去尽早发现这些变化。而档案在开发过程中的价值需要我们在另外的主题中详尽的讨论，但是至少我没有看到有几个公司把在项目的成本中列入了档案的费用，也许你是一个特例。
同时我要告诉你，现在很多变化就是无序的，或者说你是不能发现这个序的。我们的根本任务就是在这个困难的场景下进行工作。而从根本上说序的问题是不可能被根本性的解决的。同时是不是你记录了变化，就等于掌握了变化。进一步是不是变化是不是来得及被你记录下来，被你理解下来。当然这些和文档的作用没有直接的关系，我们可以暂时不讨论。
同时你说：“国内绝大部分使用UML,或者提倡不写文档的公司，做设计的深度和设计的工业化程度远远没有达到他们的层次。”这句话让我理解为，设计的深度和工业化的程度可以从文档的数量上体现。为此我给自己准备了点安宫牛黄。首先设计的深度体现在对意图的把握和反馈的及时反映上，而不是阐述在细节化的文档上。同时请你去查查设计这个词的解释，看看细节化是不是合乎设计的本意。而非细节化的东西，我确实看不出会带来大大的量。而工业化的程度主要体现在对产品的自动化的管理上，而我就不知道你能提供什么自动化的文档管理工具和维护方法。代码可以被自动化的管理是因为其是形式化的语言，而对于自然语言产品的维护也许你能有什么好的办法（当然我相信你没有，因为你是曹晓钢，不是大师，也不是人工智能的狂热者，还是一个诚实的人，）
其实我并没有把文档都打到，我只是告诉你们不要对文档报太大的希望，这只是一种辅助手段。文档不可能给你带来生产力的任何提高，但是文档不好确实可以阻碍生产力的提高。你要明白这个差别。我们不能因为代码是最重要的，就只有代码没有别的。但是也不能因为别的也很重要就认为代码不重要。更不能干脆就认为“注释和文档是程序质量的一个极其重要的部分，怎么强调也不为过 ”。
最后还是结合点例子说说明白，特别是你自己就提出了一个好的例子。你说：“比如说访谈纪录。有没有做到把每次和不同的客户的访谈都记录下来？这样日后才能有迹可循，才能知道站在整个系统不同层次的用户的真实需求。”那么你要自己写这个访谈记录呢？你是不是想过用录音代替这个文档呢？至少我是不提倡写这个文档，我提倡的是写客户访问备忘录，并且这个备忘录是需要客户签字确认的，否则就是无效的，不被承认的。而当一次2个小时的谈话，基本上也就是浓缩为一个2页，绝对不会超过1000字的备忘录。我想这个量文字应该在30分钟完成，否则说明这个文档的写作者自身对于这个文档的内容是不能完全理解的，因此这个文档也将是失去众多的价值的。而你的客户所能接受的这个文档阅读工作的工作强度大概是在15分钟以内，这个时间刚好是可以完全阅读一次这个文档的时间。如果客户在这个时间内阅读有问题，则说明你的文档的书写和文档内容理解有问题。而当你不考虑这个量的概念的时候，最容易犯的错误就是完整的记录这个谈话的所有内容。这样作的一个最大问题是，最后很难被客户所签字确认，而任何没有客户签字确认的需求文档，在我这里都是垃圾。其次由于内容过多，很难体现重点，这是由于重点未必是那么理解有分歧的地方，而分歧所带来的讨论的量是最大的。同时分歧往往是不是一次可以解决的，过早的把分歧固定下来，会对客户和你带来更多的敌对。完整的记录同时还会记录下很多无用的干扰信息，这对理解需求所带来的危害是最大的。当一个没有参加这次讨论的人去阅读这样一个完整的记录的时候，他们往往是不安装这个记录所描述的场景中交谈的人的意图去理解他们的表达，环境造成他们在不同的行话系统下对统一的问题作出了完全不同的解释。而这是在需求解释过程中所应该最大限度的避免的。因此这个文档必须保持最小的一个量。而你可能会觉得这个量的大小不好把握，特别是害怕量过小，从而忽略了什么。其实这个担心完全不必要，因为客户需求签字确认。当他们看到有些他们需要表达的东西，并且已经表达的东西没有列在这个文档之中的时候，他们的反映是可以预见的提出置疑。而这个置疑恰恰是你所需要的一个需求重点的提醒。
当然如果大家希望了解书写文档各个方面，我有时间是可以满足大家的这个要求的。至少我比在座的绝大多数的人书写和教别人书写文档的时间和量都大的多，我自己认为我是有这个资格的。

lean是参加了，是我一时生气写错了，lean也算是agile的一种。

这一点很显然，困难在这里就是等着我们去解决的，我也不会认为如果索性把中间文档全部丢掉，反而是一种可以接受的解决方式。




我从来就没有准备解决有序性的问题，在这里的一个焦点是，如果不记录变化，更加谈不上掌握变化。不要倒果为因。



你这样反倒让我颇为不解，到底是如何得到这一结论的？设计的深度和工业化的程度当然不是从文档的数量上体现，而是从质量上体现。




工业化的程度主要体现在,参与项目的各种人员有自己明确的任务和目的,能够在一个可预制的交涉框架和反应烈度上进行讨论.或者说,就是CMM提到的"可重复性".




到这里我发现oz6的一个特点,就是喜欢替我预设立场(我从未说过工业化是自动化),并且把这个立场推进到一个比较荒谬的地步.但是真理前进一步就是谎言,而这一步,我是不会跨出的.



我认为注释本身就是代码的一部分,在这一点上javadoc 和xdoclet比我有说服力. 文档的确是程序质量的一个重要部分,当时"怎么强调也不为过"这样的话,我是不会说的.

下面的访谈纪录的例子,非常高兴,总算在这一点上你举的例子的确就是我说的意思.看得出来你是做过访谈纪录的. 我要说的是,我所说的访谈纪录恰好就完全是你说的备忘录,包括时间,概略,签字等等.



这才是你整篇回复中最有价值的部分.具体到量的问题,就只有完全看经验和教训了.
只是看到这里我非常奇怪,看起来oz6和我经历类似,就是我说的那种已经有了高质量文档经验的人,却得到和我完全相反的经验,除非是已经得到了一个完美的团队,可以直接通过代码交流,并且日后接手的团队也完全可以一夜之间阅读完数万行代码,并且精确的领会意图.

你我的分歧就在这里,我坚持认为,一个保存了项目完整信息,包括变更信息的可以搜索的数据库是有价值的,而你认为不是.

晓钢，别生气啊，有什么好气的。关于 Lean 的书我这里是这本：
《敏捷软件开发工具——精益开发方法》，（美）Mary Poppendieck & Tom Poppendieck 著，清华大学出版社出版。
这本书的序一是 ASD 的发明人 Jim Highsmith 写的。在前言中作者写道：

在绪论中，作者写道：
似乎不需要更多的证据证明 Lean 属于敏捷方法和反 CMM 的本质了吧？
这本书的厚度与书中介绍的开发方法名称一样 Lean，只有 150 页。一个周末读完没什么问题。
BTW，Lean 的人有没有参加那次敏捷宣言的大会是我乱说的，他们并没有参加那次大会。大家可以板砖伺候，呵呵。

看了这么就JavaEye。
这还是第一个争论比较激烈的帖子；（可能Hibernate论坛上也有，那里我不怎么看）。

个人觉得文档的重要性很大程度上取决公司的过程，如果是重型方法，那自然文档是很重要的；如果是轻型方法，那就不中要了吗？也不之，个人觉得只是多余少的问题；

文档应该是代码的概要，和代码的补充。

个人觉得，文档不再多少，目前还在讨论要不要写文档，我觉得重要的是如何管理文档。文档与代码和设计同步才是最重要的。

不然，文档越多，障碍越多；这一点我赞同o6z。阑尾项目，文档多了，很容易把人引入地狱。

另外，曹晓钢关于文档数据库的管理，很值得借鉴。文档的版本管理，和各个版本的却别比较不是件容易的事情（一般使用Word编写）。

文档多少并不是问题，文档的质量和与代码和设计的同步才是问题。

看看Apache上的项目（也许那不叫大项目），那里并没有我们说的那种文档，
即使有也是很少。

根本问题在于一些人不思考问题的核心是什么，而被怒气干扰了他的正常的思维。比如曹晓钢不知道为什么认为lean不是敏捷（当然他现在承认他是生气了）。而实际上他不知道lean的来源不是日本，根本不是什么丰田之类的作品，而是DoD的一个研究成果（这个只能说他们没有看过这个书，我看过并不是我比别人高级，而是因为我要给一些鸟人讲生产管理的思想发展史，要是只考虑开发软件我研究这个干蛋。）
而这个问题在我们的实际工作中经常性的存在，因此会造成大量的无用而有害的垃圾信息。你首先就应该去辨别这个东西，并且把它们从文档中剔除。这样你的文档的量将大大降低。
一个产品的质量决定于对其涉众的关注的满足，在不同的人的视线这这个属性会有所不同。而作为一个工业产品必须在前期就明确其涉众的范围，而把资源都投入到满足这些人的针对性需求中去。而这个范围一旦固定下来，其优先的程度一定也需要被确认。而不管如何资源一定是受到限制的，而所有人的质量考虑也是必然会有矛盾的。而文档在软件开发过程中所消耗的资源往往是被人们所不能清楚的考虑的，其生产的所消耗的资源大家都希望从今后的对其应用过程中所收回。但是如果你不能确定这个资源所消耗带来的产品会不会被使用，以及在什么时间使用，这样的产品就不能被认为是合乎工业工程要求的产品。而这些产品必然会带来各种利益分歧的涉众的某种反映，如果不对其质量和数量进行严格的限制显然也是一种非工业化的活动。而任何一个产品在一个工业过程中，都有其恰当的地位，任何所谓“不管怎么强调都不过分”的说法自然不能被认为是一种工业化的阐述。
最后说说这个：“有文档的CVS, 也有自己的kowledge base, 还有bug trace 数据库,这些都支持全文检索. ”首先文档CVS的说法显然是一种没有经过他思考的气话，CVS对于代码的管理和对于文字的管理的区别我想曹晓钢是明白的。而所谓的kowledge base是不是就是文档的集合，我想他应该也明白。同时全文检索就能代表被管理了吗？我想曹晓钢应该又一次因为生气说了不该说的。同时我想曹晓钢知道bug trace是怎么来的，这是一种自动化是文档，格式单一，维护简便，其实质只是编程过程中的某种数据的自动提取。然而我想他一样明白类似的数据在编程过程中是多数还是少数。
而进一步我必须再次说明文档是难于被跟踪的，难于建立其联系的，难于被理解的－－当然这是在机器的角度上的观点。而我想谁也很明白你很难把一个需求的改变直接和文档中的某种变化联系在一起，更难于和代码的某个变化联系起来。而同时文档和代码对于变化的反映也是不同步的，而这些不同步是文档难于被人理解的一个重要原因。同时人的阅读和理解能力有一个限度，并不是说越多越细节化，就越好理解，必须保持在某个粒度之上才是合适的。而不同的人的粒度又有所不同，但是你不可能为所有人维护一个系列的不同粒度的文档体现，也根本不可能在这些不同粒度的文档中保证实时的同步。而更加应该注意到的是，设计的种种思路，如果不去建立在某种具体的实现之上将毫无价值。而在软件开发过程中这些具体的实现将被无限次的自动重复，并不消耗任何资源，这也使其设想和实现的距离变得非常的进。而同时对于一个设想的表述要大大难于对于一个实现的表示。同时设计的时候会有种种的权衡，如果你要把这些权衡都写到你的文档之中，而不去用具体的实例验证其合理性，就将是一种垃圾信息。