如何look注释

对于注释而言，我很不太喜欢以下二类人:
1.完全不写注释.
2.用英文写注释.

事实上,说"命名即有很强的注释性",和上面用英文写注释完全没有什么两样.你以为你是谁?是二鬼子吗?十句中文夹杂着5句英文,就很高明了吗?

1.你的英文很强很标准吗?
大多数的中国人,恐怕都不怎么样吧.你英文标准了,其他程序员英文不标准理解错了你的意思;你的英文不标准了吧,其他程序员英文标准的,也理解错了你的意思了.
2.写注释(专指中文注释)给谁看?
不但是给他人看,也是给自己看.
每个人都有自己的写作风格，你不可能强求他人与你的风格接近，也不要以为自己的风格就是完全正确、万年不移。所以要尊重他人。
而尊重他人的办法，就是在写代码的时候，把自己写的每一个代码的意图讲清楚，让他人查看的时候，能够以最快速的时间理解清楚（因为你是中国人，理解中文比理解英文快一万倍。不要以为写了英文代码自己就跻身老外阶层了），节省他人的宝贵时间。同理，他人如此做，也就节省了你自己的宝贵时间。
同时，写代码也是给自己看的。做项目，必然需要进行后期维护。如果没有详细清楚的注释，一个项目半年后、一年后进行维护，不管是谁写的，主要的流程业务什么的，还是记得住的；但没有任何一个人可以保证，具体的代码书写意图还能够记得清清楚楚、宛如昨天。即使有注释，也会经常在某个方法上思考：咦？当时为什么要这样写？更不用说没有注释的情况了。
3.写注释和代码长短没有必然的关系.
代码长就是不好吗？代码短就是好吗？
似乎，“每个方法不超过20行”，多精确简洁啊。然而，即使是数据库里面，也存在“冗余”的这种说法，数据库设计是要讲范式的，但所有地方你都讲范式那你就是找死－－因为范式是不考虑性能的。
有些家伙，往往从一个极端走向另一个极端，要么代码写得挤成一团，要么就像一样，精简过份。
过份精简的后果，就是调用的关系变得很深，就像一个公司，最理想的情况，是老板直接指挥每一个员工（类似代码都挤在一起），效率最高，但往往老板没有如此多的精力；因此老板痛下决心，要各就其位，各安其职，在老板下设副老板＝》总监＝》部门经理＝》项目经理＝》项目小组＝》开发人员，看起来好像很理想了，但实际上运转起来，比老板一个人指挥还要不堪－－一个小公司而已，搞那么复杂做什么？
理想的代码，是适合少代码的时候就要少代码（很多时候，为了以的的可扩展性，往往直接继承某个类而里面根本一行代码都没有），适合多代码的时候就要多代码。要求方法执行单一职责当然是没有错，但万事都不能绝对。

给大家讲一个真实的事。
我公司在福建，DELL公司就在厦门。有一次，要买一批DELL的服务器，按照规定，必须三家比价。服务器厂家、型号已经是定下来了，按理说，直接找DELL公司采购进来，价格、成本是最低的；但是为了遵循这个规定，就一定要找三家DELL的经销商来比价，硬生生自己抬高了价格。

我不知道以往的代码经历是什么样的。估计都没有怎么样和别人配合过，也估计从来没有修改过别人的代码，所以心安理得的不写注释。但你要知道，一般来说，别人在修改你的代码的时候，如果你连注释都不写，那么往往是一边在问候你的直系亲属，一边在修改代码－－这又是何苦呢？

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

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

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

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

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

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