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

Lean programming 我自认为了解的还是比较清楚的，因为今年三四月份ddj china上刊登的那篇Lean Programming的文章就是我审的，花了我接近一周的时间字斟句酌。而其实我在工作中也接触到非常多的Lean 的思想观念。因为实际上丰田就是我们的大客户，我们在合作项目的过程中，非常深刻地从实际学习过Lean的表现。

CMM我赞赏的唯一一点，就是其“可重复性”，他把可重复性作为起始，他的繁文缛节确实令人难以忍受。这不能抹煞“可重复性”的重要性。

Lean 其实是一种着重人的管理因素的方法，在他的原则中，很少直接指出开发/生产应该用什么样的方式，他提倡的是各个环节互相负责，减少环节中的时滞和信息损耗，从而提高生产率。回到我上面的说法，这就是一种工业化，当变化能够没有凝滞的通过各个人的案头，才能完成本来应该做的事情。在工业上，Lean production主要应用Kanban管理，一个Kanban保存一个待加工的零件从起始到最后被消费的所有工序信息。在我的设想中，在软件工程中，“变化”就是一种待处理的零件，而我们只有记录他，管理他，减少在处理流传环节中的时间损耗和信息损耗，才是提高生产工业化的道路。

Lean的另外一个原则就是，要通过各个环节的互相负责而激发各个环节的人员自己的创造性。从开发来说，就是设计人员要能够为开发人员着想，接受客户变化的人要为下一步处理的人着想，编写程序的人和打补丁的人要为日后的人着想，才能尽量减少“变化”处理的流程时间。

为了达到这个目的，实施Lean production的工厂工人在自己的工序内有自主权，他们会意识到自己的步骤对整个流水线有影响，而工厂的效益和自己的效益息息相关。

看到这里我真的是吓了一大跳，难道我以前审的稿子原文就出错了。嗬嗬，幸亏我手头还有这篇稿子的原文，这就是Lean Programming 一书的作者，Mary Poppendieck自己写的，大家自己看看到底Lean Programming和toyota的Lean production有没有因果关系吧！

Lean Programming

Assembly-line production techniques apply to software, too.
Mary Poppendieck

In 1935, Kiichiro Toyoda, the son of brilliant inventor Sakichi Toyoda, founder of the Toyoda Spinning and Weaving Company Ltd., dreamed of providing vehicles to the general public. After a hiatus imposed by World War II, he chartered Taiichi Ohno to design an efficient production system for high-quality automobiles. Over the next 30 years, Ohno developed the Toyota Production System (the d morphed into a t when the company reached the import stage), now known worldwide as Lean Production (see The Machine That Changed the World: The Story of Lean Production, by James P. Womack, Daniel T. Jones and Daniel Roos, New York: Rawson and Associates, 1990). The foundation of Ohno's system is the absolute elimination of waste in both product and process.

Lightweight methodologies, adaptive software development and Kent Beck's Extreme Programming techniques have, in effect, applied the simple rules of Lean Production to software development. The results, which I call Lean Programming, can be as dramatic as the improvements in manufacturing engendered by the Ohno- and Deming-based efficiency movements of the 1980s. The Chrysler C3 project, which used Extreme Programming, with its characteristic focus on teamwork, customer feedback and continual reintegration, is a prime example of this new methodology.

Lean production 并非是Deming的功劳，Deming从美国去日本的时候，只不过是一个籍籍无名的家伙，到了toyota才受到重视。直到后来日本货在美国长驱直入，Lean Production才反过来受到重视。当时在toyota,并没有出现Lean这个词语，他们叫做“全面质量管理”，后来是MIT的Daniel Roos把它叫做“Lean Production”,后来才有“Lean management, Lean Programming”等等，不过反过来说Lean和日本人一点关系没有，我怀疑也只有你才会这样认为吧！

我同意“没有人”的看法，FAQ, 2 minutes tutorial等等这种简洁的文档价值最高，你看很多open source项目都是把这些文档的link放在显著位置，看了这些文档以后，就能基本了解明白项目的架构，要深入理解它的应用的话，再找对应的unit test code去看。

因为code和文档相比，有一个天然的优势: 无歧义。对于准备从事技术这条路的人员而言，首先应该学习的是怎么写美的代码，而不是写看上去很美的文档。

嘿嘿，没想到一时的错误，反倒引出这么多离题万里的东西。更没想到还上了没有人的当。除了怪我笨，还能怪谁。

让我们排除这些杈出来的东西，回到最初的话题来，在oz6的上一篇文章里，除去开头的一些废话，后半部分才是我们值得讨论的话题：



在此，我们再一次体现出分歧。你文中的文档，仍然代表的是正规的，符合某种编辑标准的文档，而我在一开始就明确提出，我并不是这种文档的支持者。在诸多敏捷开发的书的语境里，都是把这种文档作为讨伐的对象，而我们在这个帖子中，主题是楼主提出的“文档”，在其中，并非是指那些CMM中用到的正规文档，二是指程序开发中用到的注释和模块文档。楼主后来也经过说明，他是在公司内部编写模块的过程中，便写文档给其他消费者使用。比如说，apache的项目大多都有完整的manual,更别说hibernate和spring.

并不是我被怒火蒙蔽了眼睛，而是你们自己审题不当，在没有了解情况的把文档就抓到自己熟悉的想法上。手里有把锤子，就把什么都当成钉子。

好，让我们继续这个话题。回到oz6上面的主题中，需求的改变和代码的变化不是不能，而是完全可以做到的。在issue trace中记录这个改变的需求，然后在cvs commit info中，在代码注视中记录这个编号，是完全可行并且方便的。

当然，在word形式编写的，诸如“客户访谈纪录”，或者“需求分析”中，是无能为力的。

你说到，“而更加应该注意到的是，设计的种种思路，如果不去建立在某种具体的实现上将毫无价值。而在软件开发过程中这些具体的实现将被无限次的自动重复，并不消耗任何资源，这也使其设想和实现的距离变得非常的进。而同时对于一个设想的表述要大大难于对于一个实现的表示。”

这应该才是你真正的意思，因为你一直是在追求一种“对设计的表述”，如何进行着一种表述我现在也是毫无头绪，并且这也是每个人所应该认真思考的。而这，和我们对项目文档的讨论，并无太大相关。我们讨论的，是现在在具体的项目中使用的，包括从设计到实现到变更的各种信息（我宁愿不用文档这个词语）。

曹晓钢
不客气的说这里我肯定是一个制造高质量文档人，但是我们的观点是这么的不同，这里没有任何可以遗祸的，关键在于你是不是有一个工程化的解决问题的态度。
首先我们的分歧在于：“这一点很显然，困难在这里就是等着我们去解决的，我也不会认为如果索性把中间文档全部丢掉，反而是一种可以接受的解决方式。”工程化的态度是使用最成熟最有把握的手段实现其最根本的目标。感到困难肯定是一种对手段的能力不能把握的感觉，这一点绝对不是我强加给你的。在工程中遇到困难本质上说就是一种工程化不成熟的表现，而迎着困难上则根本就是一种和工程化态度背道而驰的体现。
“我从来就没有准备解决有序性的问题，在这里的一个焦点是，如果不记录变化，更加谈不上掌握变化。不要倒果为因。”所谓序就是追求因果，所以你还是在那个圈子里转圈。变化被记录，但是是不是所有的变化都需要记录，这显然是否定的。掌握变化的核心在于对变化的快速反映，这首先是对于变化的快速发现。文档只是对于变化的一种反映，并不是变化本身。同时我请你再次注意文档和档案的区别。
“工业化的程度主要体现在,参与项目的各种人员有自己明确的任务和目的,能够在一个可预制的交涉框架和反应烈度上进行讨论.或者说,就是CMM提到的"可重复性". ”这显然是你最愚蠢的一种想法（注意用词有些过分，但是实在找不出更加确切的词汇，因为作为一个有如此经验的人，有这样的思想，只能是被认为是愚蠢）。我们所面对的需求应该是不可重复的，并且随着我们的能力的增长这些不可重复应该是越来越巨大。而由于其上游的资源是一种不可重复的，对于这些资源的处理方式一样应该是随着变化而发生变化的。一个组织的工业化程度越高，处理问题的能力越强，其对于上游的需求来源则必将根本性的不同，其开发的过程也必将随着这些变化而发生变化。一个组织的开发过程越是可以被重复，并且这个重复的程度越高，就只能说明其处理问题的能力越是低下。当然开发过程的变化有两种情况，一种是高能力下的变化，一种是低能力下的变化，但是可以肯定的说变化是低能力的。
“到这里我发现oz6的一个特点,就是喜欢替我预设立场(我从未说过工业化是自动化),并且把这个立场推进到一个比较荒谬的地步.但是真理前进一步就是谎言,而这一步,我是不会跨出的. ”我从没有说这是你说的，问题在于这恰恰不是你说的。工业化的本质就在于自动化，而不是过程化，以工厂可能生产的过程经常性的发生变化，一个作坊往往其生产过程是百年不变的。而文档的大多数不能被自动化处理是其成为一种工业化手段的最大障碍。问题恰恰就在于你没有说这句话。
对于javadoc和xdoclet在我看来只是另外的一种代码而不是注释，注释是可有可无的，只是用来说明代码的，这两者显然不是。同时我认为随着CASE的更加进入各种开发过程（这是我最讨厌的），注释的书写将变得越来越困难，越来越成为一种bug的新的增长点，这显然值得大家重视。
问题的最后，也是你最不能被我容忍的一点是：“具体到量的问题,就只有完全看经验和教训了”。这显然是一种非工程化的一种说法。我的答案是：足够的少。这个说法似乎很虚，其实这是和客户和组织的具体状况紧密相关的。得到这数据的过程很简单，就是尽量少的制造文档，只是当涉众对真正产生现实的需要的时候才制造这个文档。而当这个需求被完成后，则只保留最直接的对应部分，而把各种中间产品都抛弃（工程学的基本原理，只生产产品而不生产中间品）。
而在这个例子里面，其实我们的区别是明显的。客户走访记录觉得不是我说的那个客户访问备忘录，记录就必须是记录，其有时间的顺序性，必须关注细节，必须中立。而我说的备忘录，只有时间点而不存在顺序，尽量性的去忽略细节，其反映的是利益者的观点而不是中立的观点。这其实就是文档名称的一种规则，也是区分文档和档案的一个差别点，请细致体会。
阅读10000行代码和阅读代表这10000行代码的文档所消耗的资源究竟谁大谁小是不好比较的。在我遇到的多数日本企业中，我宁愿去阅读代码而不看他们的文档。同时阅读这10000行代码，未必就是直接去读代码，你可以利用很多工具生成uml之类的代码概要。而你阅读文档我确实没有看到有什么工具存在这个功能。同时你的观点我引申一步（可能又是我强加与你），就是阅读这个文档比阅读这些代码更加简单和消耗时间少。我想这只能认为是你的文档数量大大少于你代码的数量（我不考虑代码是不是清晰，任何一个组织不能书写清晰的代码，文档再清晰，其实际的能力依然被我认为是低下的）。而这个文档的量越是少，简单的说我阅读的时间将更加的少，直到一个阅读的拐点——由于数量过少而带来的不可理解。在我看来尽量接近这个拐点是可能的，并且应该是从低向上去接近而不是从高向低去接近，也就是尽量少的投入资源，逐步的过渡到拐点。
重视不重视文档，并不在于其数量，也不在于是不是投入更多的资源，也不是是不是更加看重文档的作用。而是更加现实的认识到文档的缺陷，更加小心的使用。
而对于“我坚持认为,一个保存了项目完整信息,包括变更信息的可以搜索的数据库是有价值的,而你认为不是.”这可能只是我们最小的一个分歧了。其实我更看重文档是不是能更好的说明程序的当前状态，而不是他的历史。

按照曹晓钢最后的一段话，我们的分歧就不是很大了。
按照我的理解，楼主最初的意思好象是试图通过大量的注释和文档来达到改善交流，降低学习成本的目的。甚至把这些注释和文档夸大到高于程序代码的地位。我反对的也是这一点。因为如果代码本身问题很多，依靠大量的注释或者文档只能说是隔靴揣痒，或者只能起到除臭剂的作用。这样的伎俩我也会的，但是我更愿意在代码本身上面多下些工夫。“源代码就是设计”是有前提的，不是所有的源代码都是设计，我认为经过严格重构过的源代码才是设计和文档。其实解决这些问题老外也没有多少好方法，现在大家觉得写自注释的代码肯定是有效的方法之一。但是还是有一些复杂的代码，尤其是包含了精巧的设计在里面的代码，即使原作者认为非常容易理解了，在其它人看来仍然是晦涩难懂的。这时候就应该多写一些文档。

话说回来，这些都是要成本的。成为一个完美主义者是要付出巨大代价的，所以大多数场合其实就是一个权衡。样样都做到 100 分，我相信你肯定能做到，但是我确实很差，我可能永远都做不到。我现在可能在最重要的方面（当然也是我认为最重要的方面）能做到 80 分，在其它相对次要的方面（仍然是我自己的理解）只能做到 60 分。但是最重要的是我一直在向前走，一直在不断在为客户提供新的价值，这也是我现在还能活下去并且幻想着房子车子的原因。

Lean 的那本书里有这句话：
它们对记录成功有用，但通常会妨碍创造成功。
很耐人寻味的一句话，你的成功真正是因为写了这些注释和文档吗？呵呵。

      呵呵，楼主，知道答案了么？
    很多人写程序就喜欢逞强，越晦涩越好，别人越看不懂越好。
    看看国外的开源代码，能力除外，简洁更为突出！

看得好累，吃不消看了，我喜欢实际一点的。

就说注释好了，比较一下：
1。可运行的代码
2。测试代码的单元测试和其他测试
3。注释

这个重要性应该是向下递减的。没有1，其他都没有意义了。没有2，就没有一种可执行、可重复的方法来验证1的正确性。

至于注释，对于程序的功能、正确性和可靠性，对于客户来说是没有任何意义的，所以除非有特殊的理由，我们才去写注释。

一般来说，坚持写注释的人最重要的观点是便于自己或后来者理解代码，减小程序维护和变更的成本。这个我们当然喜欢，
但是要注意几点：
1。注释到底是不是最好的工具来加快和精确理解
2。达到这样的目的需要多少成本

第一点，首先绝大多数注释是细节程度上的，基本上和代码本身处于同一层次，因此我们需要看一看代码本身是否比注释更有权利。
注释的目的基本上是为了说明
1：代码实现中的权衡
2。代码本身的目的
3：别的代码使用该代码的方法

以Java举例，注释包括包注释、类注释和方法注释。在99%的情况下，我认为只有包注释和类注释才有意义，因为一个包和
类只有自己的名字来解释自己的含义，如果是一个简单的类，譬如说是Rectangle，当然这个名字已经说明了一切。但很多时候，
一个类里面包含很多方法，很难简单地用一个类名字来描述整个类的意图和作用这个时候，这个时候代码本身是不足的，需要
类注释的。

对于方法层次上的注释，除非你这个方法用了非常复杂的算法，那么我们最先关注的是它的目的，这个目的用方法的名字就足够了，
如果你认为它有三个目的，或者有几个阶段，那你必须重构，直到达到这个目标。这里代码比注释的好处是能够优化代码本身的结构，
易于重用和新变化，没有同步的成本，更重要的是它是可执行的。

有的时候，例如内部实现是错误的，我们需要修改代码，这个时候我们也需要理解这个代码地实现方式，但我认为一旦达到了
上面的要求，对一个程序员来讲，代码更精确、更简单地能够被理解，而不是注释，除非注释逐行解释代码地实现。

至于别的代码如何来使用你自己的代码，我不由得回忆起当初学习delphi地经历，在我使用一段delphi以后，我很多时候都是凭自己
对delphi函数命名的习惯的猜测去调用一个个函数，而不是依靠delphi地API文档和delphi源代码里面的注释（实际上非常少），真的无法理解就去看源代码。而
对于一些我完全是初学的类或者函数，我的做法首先是去寻找范例代码理解函数调用的顺序，至于这种理解是否正确
最终取决于我自己的不断测试。对于一些复杂的方法，我会在基本已经理解，并且能够使用的情况下再去看是否还有别的什么"诀窍",后门
等等。因此，在这方面单元测试无疑比注释更有用，但是如果一个方法确实比较复杂，并且不同地类和函数之间有一定的依赖关系，我们
需要专门的API文档，注释根本做不到这一点。

第二点，注释的成本。注释无法验证，注释不能执行。因此，注释必须完全通过手工来进行维护，当一个类被重构为一个类层次，
当一个方法被抽取成两个方法，当一个类的某些方法被移到另一个类，一个类地实现被改变（接口不变）的时候我们都必须手工去维护
这些东西，并且无法知道我们的注释到底是不是正确揭示了这个类、方法的意图和实现思路。这个成本是非常高的，特别是当我们
知道注释既不能为客户提高更多的价值，也不会对其他程序员理解代码有多大的帮助。当然，如果我们有足够的人力、物力愿意干这样的活，有些时候也会稍微有点帮助。

曹晓钢
其实你还是理解错了，JIT并不能被理解为lean，不过你知道就好了，没有必要去玩这个概念。lean来源于JIT，但是确实不是一个概念。这个其实就是日本为什么在90年代以后落后的原因。
关于文档，我还是坚持严格意义上的定义，这并不是我看到什么都是钉子。比如文档的存储和检索，如果不建立某种格式的定义就十分的困难。而同时我们必须知道不是所有的程序都是工具，因此对于客户手册的书写也不是要求相同的。而实际上对于这些类似的javadoc和manual是最终产品的一个部分，而不是中间状态的文档。对于最终产品和中间体不能采取同一的测量。同时请注意大量的交流中应用的非正式的文档是没有办法电子化的。
下面其实才是一个关键的分歧点，也就是你认为维护需要文档。当然这个确实存在某种对文档的需要。但是对于维护来说，更重要的是代码的清晰和测试计划的完备，而最后的不得已的办法才是使用文档。而同时你也必须注意到，文档同样存在一个维护的问题，越是以来文档，这个维护的问题就越是难于解决。