爲何寫註釋必須成爲編碼的硬性標準（雙語原創）

爲何寫註釋必須成爲編碼的硬性標準（雙語原創）

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*