为何写注释必须成为编码的硬性标准（双语原创）

为何写注释必须成为编码的硬性标准（双语原创）

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 niubilitied man or lady you are. 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 for this article.

*Written by Wayman Qi*