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

《最后期限》是汤姆·迪马可（Tom DeMarco）写的书，他和人（蒂姆·利斯特）合作的《人件》可是软工经典之作。

我倒是觉得《最后期限》中的故事很不错，而且每章结尾都有基于团队的项目管理方面的原则，几乎涉及到项目管理的各种方面，自我感觉还是比较有意思的。

后山说得是，下班回家的路上，我为这个还怀疑了一下的，结果果然是说错了，这两天在看《人件》，觉得以《人件》的那种行文方式，我似乎更乐意接受一些，毕竟那个DeMarco编故事的能力实在是有限。

作为小说来讲，《最后期限》自然是差劲的。DeMarco写过一些普通小说，不过销量不咋地。但这本书毕竟是第一本关于软件项目的小说，价值在另一方面，对吧。

谈到这个文档的话题，我想关键是每个人要对别人有责任心，要爱他的队友。只要他爱自己的队友，他希望和全队一起获得胜利，那么具体到每个时候，是带球突破还是传球，至少在大方向上是不会错的。

还是得看看的！

    什么叫我的理解力需要提高？？？我什么时候说了这句话是从大家讨论中理解出来的？我是现实中看到的。有相当多的人程序根本就没有注释。注释当然不是越多越好，那些说了等于没说的注释肯定是祸害（就如同为了文档而写文档一样，都是废的）。
   不过说什么程序结构清晰就可以代替注释？什么叫清晰？某段代码还是某个功能？注释分为两种，一种是说明式的，比如类、API函数注释，他们是必须的，标识出作者、API的使用，实现。另外一种就是解释型的，对于非常简单的程序，写解释型的注释自然是脱了裤子放屁多此一举，但是对于稍微复杂一点的算法流程，如果没有注释，没有相应的流程图，关一个人看程序，非常容易出现误解和浪费时间的。而且，如果要做代码审查，想很快找出代码中的逻辑漏洞和问题也是相当困难的。
    我前一个帖子的言论是非常反对，不要动不动把注释看成累赘，而其他人也不要为了迎合自己投机取巧的想法而赞成，这完全是一种托词，非常的不负责任。注释相对于编程，时间和精力少得可怜，而只是这少少的工作，可以给自己，给同事，给整个项目带来多少方便？
    让我想起来，我刚大学毕业进入一家比较大的公司，最开始的工作就是为已有的程序写注释（那时候前面的人不规范，没有什么注释），把我和很多同事都害苦了，不过也是受益匪浅的。

凤舞凰扬
不知道你作不作代码审察，我的一个原则是单纯的代码审察绝对不看任何注释和提示。逻辑的问题和漏洞很容易被注释所误导而不是所提示，道理很简单如果是单元测试没有发现的逻辑问题，那么一定是一种对逻辑的理解混乱，而这个混乱如果是不能被编写者发现，那么一定是很显得合乎逻辑，而这给审察者的误导是绝对巨大的。
同时我不知道你是不是意识到，如果一个算法流程需要用注释去说明，本身就代表其内在的逻辑还不够清晰，这个时候注释只是一种治标的方法。
注释其实给工作带来的危害绝对大于其所产生的一点点利益，并且随着各种工具的发展，这个危害会越来越严重。大家往往不能意识到其实维护的工作今后将大量依靠工具而不是人手工，而对于工具目前普遍的做法就是在注释中添加各种标签。实际上你的注释终将有一天会成为一个现实的bug，给你的后期维护带来根本性的麻烦。当然这只是一种远期的状况，不过我认为这个期限不会太远。
实际上注释的大量使用实在是当场由于硬件设施的不充足而带来的无奈之举。当初为了美一个时钟周期，每一个bit都需要进行大量的工作，从而是很多本来很清晰的代码经过大量的优化之后变得莫名其妙，于是需要引入注释来作强制性的说明。而现在工程化语言的一个特征就是强调其自然语言的相似性，强调其自文档，强调自解释。
如果你是一个追求代码清晰易懂的人，就应该去尽量的减少注释的出现。

本来以为讨论已经结束了，因为前面的讨论已经说得很清楚。没想到凤舞凰扬又重提了一遍。姑且让我试试回复。

凤’的第一个观点是：注释是不可以完全被代替的。
我同意这个观点。但前提是：

我想加上一个 “2.5 代码简洁、清晰”。 没有前面的作为基础，后面的只是白做。

代码清晰我理解为：功能划分明确，内聚；代码尽可能简短，不犯低级错误。
至于后面的API使用，对算法流程的注释，大可以用UT去表达，这样我觉得更明确，更舒服。

注释是要的，只是它的优先级要低一些，写的量也要少一些。如果多了起来，“时间和精力少得可怜”这个结论就不再适用了。毕竞我还是经常重构一些函数，改来改去的。改好的程序，还要去改注释，心理觉得厌烦。

另外，做代码审查，是不是应该先独立理解了问题，然后问实现者实现的思路，若有UT的话，就跑UT看UT，最后才看别人的代码和注释？

thatway
不重构你的代码一样存在需要对注释进行修改的问题。而对于解释性注释的修改唯一的手段就是人手工来进行。这个工作是经常会发生错误的工作。如果你只是把代码看作一个静态的产品，那么注释显然是没有什么问题的。但是代码很少会是静态的，特别是当你修改了一个部分以后，你很难知道是不是其影响究竟传播到了什么地方，也就是究竟都需要修改什么地方的注释。

我做的code review也不少，并且通常是在开发过程中过一段时间就和程序员pair做的，就是边做重构边解释。

可以负责任地说，对于那些企业管理应用程序，利用重构我可以让绝绝大部分的代码注释（没有统计百分比）都消失，而我可以肯定的是经过重构的代码肯定比注释更容易理解。

说点其它，还有一本书（应该是Java集合实现），我是从头到尾做过代码重构的，目的就是为了更加深刻快速地理解这本书中集合实现的各种算法，几年前我应该有一篇写重构的短文章提到对其中的一个类进行重构的过程。到目前为止，我还没有发现任何一种方法比重构更容易来加深自己对新代码的理解。

看这么多朋友在讨论文档问题。
不知道有没有人想过在项目中使用英文编写注释？
我以前的一个经理跟我说他在国内某大公司工作时培训所有开发人员的英语，然后用英语编写文档。最后失败。

是否朋友们也想过用中文作变量的问题？

其实，注释与否有时候并不重要。如果代码别人都看不懂，注释我想也没什么意义。还是研究研究如何选择一个合适的变量名称、方法名称实际些。

对于potian , o6z提到的代码复查和重构，我觉得这才是更重要的事情。

代码能够让人看懂，注释才起作用，才能从整体上让看你代码的人有更好的了解。

不要把注释写成解释你的代码。那没有任何意义。也不要过多地在注释中解释业务逻辑，最好多在注释中写些与功能相关的代码和参考代码，那些代码与此代码相关。

多使用@see会更容易让别人理解你的代码。