标签：
Why Writing Annotation Must Become Peremptory Rule?
程序猿最烦的事：别人的代码不写注释；自己写注释。
Parodox: It is most hated for programmers that others‘code have not annotations, and oneself must write annotations.
1.注释最主要是给别人看的，供自己回顾是锦上添花
理解一个人的思想，尤其是具有深度复杂逻辑的思想，是相当之难的。这也是为何不少科学理论要写洋洋数万言，甚至一本书来解释它。如果这种思想只存在于自己脑子之中，有些人自然不会费那个劲去写，但有些人还是要写。难道是后面的人比前面的人笨吗？绝对不是。我们生活在地球上，同属人类，我们都有人类共同的弱点。人的大脑不是万能的，记忆是会淡漠甚至遗忘的。因为只有淡漠和遗忘才能让大脑高效地工作，去获取新的知识。这道理不言自明。
写代码是什么？我把它定义为用相对抽象的符号，来描述解决问题的方法。所以，它有两个特殊属性：(1)一套完备的逻辑解释；(2)一套相对抽象的表述。所以，掌握这个技术是具有相当难度的，这个星球上能掌握它并能运用好它的人比例很低。程序猿们，你们因为你们的聪明而沾沾喜喜了吗？先别忙高兴。程序猿面临其他人同样的问题：遗忘。有句老话：时间就是把杀猪刀。任你男神女神，都会被时间搞掂。再聪明的大脑也不会例外。
理解抽象的描述本来就费时间，尽管作者可能认为它已经很清晰了。但是过一段时间，不说别人，即便作者自己也可能会忘却当时写下这段逻辑描述的场景。因为程序猿多数时间是为了满足别人的需求而写代码。别人的需求自然是别人的思想。别人的思想被忘掉时，你如何保证你为别人思想所写的抽象描述不被忘掉？神仙也做不到吧。因为神仙是不会陷入自我悖论的。进一步，如果是看你代码的人呢？他（她）可能连当时用户提需求的场景都毫不知晓，他（她）又如何理解你那高深莫测的抽象表述呢？你可能会说：嗯，我是按xxx那种牛x方法写的，足够简单明了，只要你会x语言，你就能看懂。老天爷，你知道你在说什么呢？要知道，人类的智慧连理解别人的自然语言都可能出现歧义，你如何保证被抽象了的表述不会发生这种情况呢？恐怕连那些电脑语言的发明者也不敢这么说吧。这也是为何所有高级语言都保留注释功能。
所以，如果你承认你仍属于人类，请抛开自负和执拗，正视人类的弱点，老老实实写注释吧。
1.Annotation mainly aims to others, then review for yourself
It‘s fairly diffcult to understand a kind of mind of human, especially include sophisticated logic. This is why some science theories were written by a lot of words or book to explain them. If these minds only retain in brains, some people think they would not write them arduously, but others don‘t think so. Is it right the latter more awkward than the former?Certainly it‘s not. We are terrestrial, we are human, we have same weakness. Human‘s brain is not omnipotent. Memory decline so much as vanish. Brains is effectively work to get more new knowledge since declines and vanishes. It‘s well known.
But what‘s the coding? In my definition, it is described a method that solve problem with relatively abstract symbols. So it has two properties: (1)an set of entire explainations; (2)a set of relatively abstract descriptions. It‘s difficult to master the skill for majority of people. The rate to master and steer it smoothly is fairly small. Coding monkeys, are you pleased with yourself? Don‘t celebrate so soon. Programmers face the same problem as others: LETHE. The old saying “Time will kill all”. You must be killed by time, no matter how you are niubility man or lady. It is wise brain that never escape.
It cost more time to understand abstract description, in spite of author thinks it is legible.But after a while, don‘t say others, even author may forget the scene that code at that time.Because programmers usually code for other‘s requirements.Other‘s requirements certainly come from other‘s minds. How do you ensure that abstract descriptions you wrote for other‘s requirement are not forgetten while other‘s minds are forgetten? God can‘t do it. God should not swamp into paradox himself. And then, how about it is others to see your code.He(or She) knew nothing about scene client commited requirements.How did he(or she) understand the unfathomable abstract description you wrote?“Hum, I coded according to niubility method from XXX.If you master X language, you can understand them easily.“, you might say. Oh my God. What did you know what you said? You should know that devergence exist in nature language understanding to be limited human‘s intelligence. How did you ensure it shouldn‘t happen in such abstract description? I‘m afraid creators of these computer languages can‘t say that. That is why all high level computer language reserve annotation function.
So, you should discard ego and pigheadedness if you admit you are human.You must face up to human weakness and write anotation in earnest.
2.注释简化代码理解
有时，你维护一段他人的代码，需要解决其中的bug。这时，你需要通过读懂其他代码来辅助你找到bug。当你确认问题不是其他代码导致时，你仅仅需要明白其他代码的逻辑结构即可，而不必逐字逐句地去读懂。这时，一段注释良好的代码会加快你的工作。甚至你仅仅需要通过读函数或方法的头部说明注释，就可以完成这步工作。毕竟，读懂注释中的自然语言比读懂最清晰明了的代码还是要容易的多。这样的注释对别人如此，对自己何尝不是方便？有什么理由不写它呢？
对接手他人项目的程序猿来说，提纲挈领的注释加快理解整个项目代码，会更快地完成移交工作，对于后来者迅速进入角色，完成催命似的项目经理的要求，是功德无量的事。这就是为何程序猿们对他人不写注释的代码都深恶痛绝的原因。
总之，己所不欲勿施于人。在为他人代码不写注释大肆吐槽之时，认真想想自己做的怎样。你对写注释还有偏见吗？如果没有，恭喜你，你已经接受了这样的硬性规则：所有代码必须写注释。好吧，如何写出提纲挈领、简明扼要的注释超出本文讨论之列。
2.Anotation simplify understanding
Sometimes you must fix bugs in someone‘s code. You need read and understand relative codes to assit you finding bug. When you confirm the reason of bugs not to come from these codes, you just understand logical structure of these codes which not read them word for word and sentance for sentance. It shoud speed up your work at this time. You may end this step through reading head anotation of them even. After all, reading nature language from anotation is much easier than reading the plainest code. The anotation is convenient for others and yourself. What reason should you not write them?
Anotation concentrate on the main point speed up understanding whole project codes for the programmers takeing up other‘s work. It‘s eariler to finish the work takeing up from others. The benifits are beyond that the latter work in role as soon as possible to finish the pressing task from PM. This is why coding monkeys extremely detest the codes have not anotation.
Anyway, do unto others as you would be done. You should consider how do you do seriously when you complain other‘s codes without anotation. Do you have prejudice for writing anotation? If not, congratulations on you, you already accept the following preremptory rule: Any coding and Any anotation. Well, how to write plain anotation concentrate to main point, it is out of range of this article.
*Written by Wayman Qi*
标签：
原文地址：http://my.oschina.net/u/189973/blog/359352
