我为什么拒绝写注释

看了一篇博文《 我为什么拒绝写注释》 ，看了回帖，反对声音一边倒。但我和作者深有共鸣，于是写一篇博文以示声援。

 

注释本质上是另一种形式的文档，当我们来讨论注释的必要性的时，其实就是在讨论文档的必要性。注释和文档确实可以带给我们一些收益，但使用不当却会带来很多的麻烦.

 

1.可运行的代码是唯一正确反映现实的东西。需求是易变的，因此软件也是易变的，但是绝大多数公司/团队都没有精力和财力来及时的更新文档和注释，因此越到项目后期，就会越会出现注释（文档）和代码不一致的情况。于是程序中充满了虚假的注释和谎言。

 

2.当你需要用注释来说明自己的算法和意图的时候，停下来想一想，很多时候你会发现自己的设计出了问题。很少会出现这种情况：需要牺牲程序的可读性来提高效率。因为精心设计的代码往往是简练的，简练往往是高效的。

 

3.过多的注释往往会干扰程序的可读性，频繁出现的注释是一种糟糕的排版体验。试想一下，如果你正在阅读一篇论文，论文的注释随时出现文章的正文中，这是多么令人沮丧的一件事。

 

4.不要拿MSN和Framework的注释来说事。这不是一个技术问题，而是一个商业问题。Framewrok的核心价值就是代码本身，而不是具体的业务应用，因此注释也是Framework的核心价值。而你的软件的核心价值是可运行的程序以及其后的业务逻辑。在微软公司，注释往往由专业的文档管理团队来处理，你的公司又有这样的实力吗？

 

5.我们并不排斥一切文档，但我只给软件最核心，最稳定的部分编写文档，例如软件的架构。另一方面，我坚持严格把软件的文档控制在20页以内，这样可以使一个新人在一天之内了解程序最核心的部分，通过可运行的软件，新人才会建立起真正的自信和对项目全面的认识。至于更具体的细节应该在工作中了解。

 

最后附上《敏捷宣言》供大家参考

#个体和交互 胜过 过程和工具

#可以工作的软件 胜过 面面俱到的文档

#客户合作 胜过 合同谈判

#响应变化 胜过 遵循计划

虽然右项也有价值，但是我们认为左项具有更大的价值。

 

 

转载于:https://www.cnblogs.com/zhangxuguang2007/archive/2011/05/25/2056855.html