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

晚饭归来。从oz6的话语中我隐约看到另外一种方法论的银弹的影子...或许只是味道。

感谢potian出来，实际上下午交火过于激烈，我感觉双方已经失去了认真思考和仔细定义的时间。oz6的发言中充满了隐喻，而且是有很多年工程经验的隐喻。说句实话，我觉得oz6现在正处在下一次从厚到薄的前夕，最黑暗的时刻。

必须承认，我在讨论中因为和oz6的对立导致的预设立场，对有些问题比如注释已经脱离了认真思考的范围。potian已经仔细解释了关于注释在代码中的作用，自然我不需要再多说。

而potian地回答，我想已经最贴切的回答了楼主的问题。这个问题，我就到此为止了。

potian 说的太对了。实际上过多的注释妨碍了重构的进行，如果你想让代码僵化那么就写大量的注释好了，越多越好，甚至注释:代码=10:1。重构的结果往往是删除掉大量的注释，因为它们或者已经不适合代码当前的结构，或者已经不再需要，因为代码的结构已经非常清晰了。而且我并不知道是否还有可能进行下一次重构，那么我写太多的注释是不是很有可能是在做无用功？我其实只要写很少量的注释就足够了。

你的理解能力看来是急待提高。哪一句话让你产生了这种想法？这些可都是浅白的中文啊！

看来大家都很同意potian。果然是破天一出，谁与争锋啊！:D

我认为，关键不是观点的对错，毕竟大家都可能会错的，而是态度。我们前面那样“吵吵嚷嚷”，那不过是争论罢了。

而在javaeye，我想，更需要的不是争论，而是思考！大家都来思考一个问题，每个参与者就都会有收获。大家都在那里争论，不过是浪费时间而已。

单单J2EE而言，文档在维护时起的作用几乎为零

虽然曹晓钢不说了，我还是要继续说下去。
首先对于从需求到文档到代码的联系并不是那么一一相对的关系。首先从需求到代码的这个正方向看，现代软件结构已经不是那么简单的需求的直接映射，而是通过围绕以architecture为核心的开发进行的折射型的满足。一个需求的被满足会折射到不同的点，同时这个需求的被修改又可能被折射到不同的点。而你需求的变化所带来的文档的变化是可以把握同一的，但是当这个文档和结构相对照的时候是不会完全同一的。而满足需求所产生的这个architecture并不能被认为只能满足这个需求树，也不能认为这个architecture的所有部分都是为满足这个需求树所存在。这个时候不统一是必然的。而从另外一个方向也就是从代码到文档到需求的方向看，这种不对应性就更加明显。例如你经常会为了重构而修改你的代码，但是作为文档来说，这种修改往往是被驱动的，而不是驱动的。而这个修改并不能带来需求的变化。而又存在很多场合，对于局部代码的修改并不是改变了设计的意图，而仅仅只是对于局部代码的优化，可能出于美观也可能出于习惯。而这种活动在一个以architecture所指引的，使用核心资产为开发基础的开发过程中是经常性的存在的。这个时候你所面对的种种修改根本就不可能用issue trace来建立一个逻辑的联系。
同时即使这个联系是可以建立起来的，也未必带来其同步性要求的满足。首先文档是不可运行的，因此就不可能自我验证的，否则就不是文档而是代码了。而当一个代码发生变化的时候，你认同与之相关的注释所带来的变化是需要手工的，那么你是否认为与之相关的文档会自动化的修改呢？
其实根本的问题还是在于没有银弹所带来的矛盾的无从解决，也就是你即使解决了这些文档的问题、代码的问题，你依然只是不能解决根本的概念完整性问题。
最后我想你提到了全面质量管理，你应该知道质量是生产出来的，而不是检测出来的基本原理。文档和注释只能是在一个非常有限的条件下完成非常有限的工作，你并不能对其包过高的希望。
我想其实我们的根本分歧可以用你对CMM的可重复性的认同上来体现，在我这里可重复正好是说明其开发能力的低下，越是可重复就越是低下。这样的分歧来自世界观的不同，而不是具体方法的不同。
而题外的lean的问题其实刚好说明你的一种思维定式的存在，其实从lean只是agile思想的一个分支，而软件行业接受agile的时间要比agile出现的时间晚的多。当agile成为当代工业化生产的核心思想的时候，软件产业再一次落后于传统行业，悲哀啊。

这两天在看温伯格的书，实在是太棒了。1971年出版的《程序开发心理学》，至今30多年依然畅销，其中的很多思想，实在是充满智慧。抄两段来给大家看看。

P25：讨论优秀程序的要素时，关于“适应性”方面

是的，在其生命期内，多数程序都会被修改——无论其经验的多少，绝少有那位程序员能够反驳这一论断。既然如此，为什么在必须修改以前的程序时，我们总是觉得这项任务如此艰巨，以至于往往决定弃之不用，干脆自己从头写起？只要阅读过程序，我们就会透过这些程序发现：实际上，很少有哪位原作者会考虑到可能的后续修改。然而这还不是问题的本质，充其量只是症状。有人也许会问，既然程序员完全知道他们的程序迟早要被修改，为什么在编写程序时却从不考虑这一问题呢？为什么他们的程序有时甚至会让人觉得，这些程序是被恶意地搞成这副模样地，其目的是为了抵制以后的修改——就像犹如法老们的坟墓对付所有可能的入侵者一样？

这些问题的答案是有的，答案来自我们在心理学方面的研究。但是我们目前的任务，还不是要找到答案，而仅仅是提出这些问题，并在我们对关于好程序的标准进行讨论时，能够意识到其重要性。当然，一个相关的问题就是文档——因为如果不是为了是程序更加易于修改，我们为什么要去为程序编制文档呢？

P357开始，专门讨论文档的问题。

只有在把文档管理工作做好之后，我们才能体会到文档的作用。相反地，如果文档管理工作做得一塌糊涂，那么就还不如干脆不要文档。
......
接下来讨论建立“适当的高质量的文档”的含义。
......
这样，在确定如何对某个程序作文档时，我们所要考虑的应该是“谁将会使用到这些文档？”、“使用方式如何？”、“用户来自哪些方面？”、“文档将会被使用多长时间？”如果只是在局部用到，只涉及到按照设计需要处理的工作，使用文档的用户对程序员很熟悉，而且只会被用到一两年或者至多3年，那么花费在整理文档上的金钱或许应该花在其他一些项目上更好。

P367
程序员们...总是错误的认为，虽然不一定每一个人都能够成为程序员，但是任何人都能够毫不费力的胜任制作文档的工作。

另外还有一段，与文档无关。但是我认为这是最早的TDD的思想。

P272
在这方面一个好的做法就是，在对软件产品实施“修补”之前，就应该把测试程序构造好。第一点理由是：一旦软件产品（哪怕是勉强）能够工作正常，人们总是很容易就会把这段程序抛到九霄云外——因此，我们必须强制自己执行纪律。但是或许更为重要的一点就是，有时候仅仅通过构造测试实例，我们就有可能找出问题的症结所在。

推荐大家去看看温伯格的书。

庄，我趁机说一句，善意的，呵呵，希望在写类似于“定论“这样的文章之前至少把这些名家的代表作看一下

这本书我很早就前从amazon就买来了（具体那一年忘了），如获至宝那种感觉。

你看的书越多就越会明白为什么KentBeck说XP不是新东西，你可以用很多名著来对照XP的观点。

呵呵，谢谢potian的提醒。我现在在看温伯格的书。既惭愧又自豪。

惭愧的是人家30多年前，就已经想到了这么多。
自豪的是，我在没有看过他的书之前，已经得出了和他类似的结论。而且，似乎还有“稍稍超越之处”。

温伯格的书，我是打算都去把他买下来的。但是思考的乐趣，可不能等把大师的书都看完才能开始的。

温大师的书我怎么一点都看不下去啊。翻了几页就觉得乏味。怎么看都像是讲哲学的科普读物。
或许是自从那些书出版以后，对软件开发影响太大，以至于最后大多变成了常识？

那本《最后期限》，我N个月前看过中文版，与开发和项目有关的我就不说了，不过故事编的着实的没有创意，乏味的很，结局尤甚。