なぜ注釈を書くのが符号化のハードスタンダードにならなければならないのか(バイリンガルオリジナル)
6449 ワード
なぜ注釈を書くのが符号化のハードスタンダードにならなければならないのか(バイリンガルオリジナル)
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.注釈は主に人に見せるもので、自分の振り返りに花を添える
一人の思想、特に深い複雑な論理を持つ思想を理解することは、かなり難しい.これもなぜ多くの科学理論が数万語を書き、本で説明しなければならないのか.もしこのような思想が自分の頭の中にしか存在しないならば、一部の人は自然にその力で書くことができなくて、しかし一部の人はやはり書きます.まさか後ろの人は前の人より愚かですか?決してそうではありません.私たちは地球上で生活しています.同じ人類に属しています.私たちは人類共通の弱点を持っています.人間の脳は万能ではなく、記憶は薄く、忘れてしまう.淡々と忘れてこそ、脳が効率的に働き、新しい知識を得ることができるからだ.この道理は自明ではない.
コードを書くのは何ですか.私はそれを比較的抽象的な記号で問題を解決する方法を説明するように定義した.だから、それは2つの特殊な属性があります:(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.注釈コード理解の簡略化
時には、他の人のコードを維持し、バグを解決する必要があります.この場合、他のコードを読むことでバグを見つけるのを助ける必要があります.問題が他のコードではないことを確認すると、他のコードの論理構造を理解するだけで、一字一句読む必要はありません.このとき、コメントの良いコードはあなたの仕事を加速させます.関数やメソッドのヘッダを読んでコメントを説明するだけで、この作業を完了することができます.結局、注釈の自然言語を読むのは、最もはっきりしたコードを読むよりも簡単です.このような注釈は他人に対してこのようにして、自分に対してどうして便利ではありませんか?それを書かない理由は何ですか?
他人のプロジェクトを引き継ぐプログラム猿にとって、要領を得た注釈はプロジェクトコード全体の理解を加速させ、移転作業をより速く完成させ、後者が迅速に役割に入り、催促のようなプロジェクトマネージャーの要求を完成させることは、功徳無量である.これがプログラム猿たちが他人に注釈を書かないコードを深く憎んでいる理由だ.
要するに、自分の欲せざるところは人に施すな.他人のコードに注釈を書かずに突っ込むときは、自分がどうしたのかよく考えてみましょう.注釈を書くのに偏見がありますか.もしなかったら、おめでとうございます.すべてのコードにコメントを書かなければなりません.では、どのように要約し、簡潔で要約された注釈を書くかは、本稿の議論の列を超えています.
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*