Why writing comments must be a hard-coded standard for coding (bilingual original)

Why writing comments must be a hard-coded standard for coding (bilingual original)

Why Writing Annotation must become peremptory Rule?

The most annoying thing about a program ape: Someone else's code does not write comments;

Parodox:it is the most hated for programmers that others ' code has not annotations, and oneself must write annotations.

1. Comments are mostly for others to see, for their own review is icing on the cake

It is quite difficult to understand a person's thoughts, especially those with deep and complex logic. This is why a lot of scientific theory to write yangyang tens, or even a book to explain it. If this idea exists only in the mind, some people will not pay the effort to write, but some people still want to write. Are the people behind are more stupid than the people in front of you? Definitely not. We live on Earth, belong to mankind, we all have human common weakness. The human brain is not omnipotent, memory will be indifferent or even forgotten. Because only indifference and forgetting can make the brain work efficiently and acquire new knowledge. The truth is self-evident.

What is the code written? I define it as a relatively abstract notation to describe how to solve a problem. Therefore, it has two special properties: (1) A complete set of logical interpretations, and (2) a set of relatively abstract representations. So, mastering this technique is quite difficult, and the proportion of people on the planet who can master it and use it well is very low. Program apes, are you happy because of your cleverness? Don't be too busy to be happy first. Program apes face the same problems as others: forgetting . There is an old saying: Time is to kill a pig knife. If you are the goddess of God, you will be fixed by time. A smarter brain is no exception.

It takes time to understand an abstract description, although the author may think it is already clear. But after a while, don't talk about others, even if the author himself may forget to write down this logical description of the scene. Because the program ape most of the time is to meet other people's needs and write code. The needs of others are naturally the thoughts of others. How do you ensure that the abstract descriptions you write for others ' thoughts are not forgotten when others ' thoughts are forgotten? The immortal can not do it. Because the immortal does not fall into the self paradox. Further, what if it is the person who is looking at your code? He or she may not even know the scene of the user's demand, and how does he or she understand your enigmatic abstract expression? You might say, well, I wrote it by XXX, which is simple enough to understand, as long as you can read the X language. Jesus Christ, you know what you're talking about? You know, human wisdom can be ambiguous to understand other people's natural language, how do you guarantee that the abstract statement will not happen? I'm afraid even the inventor of the computer language dare not say so. This is why all high-level languages retain annotation functionality.

So, if you admit that you are still human, please put aside your ego and stubbornness and face the weaknesses of human beings, and write the notes honestly.

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 what 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 isn't 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 is 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's described a method that solve problem with relatively abstract symbols. So it has the 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, is you pleased with yourself? Don ' t celebrate so soon. Programmers face the same problem as others: Lethe . The old saying "time would kill all". You must is killed by time, no matter how is niubility man or lady. It's wise brain that never escape.

It cost more time to understand the abstract description, in spite of the author thinks it is legible. But after a while, don ' t say others, even author may forget the scene that's code at that time. Because programmers usually code for other ' s requirements. Other's requirements certainly come from the other ' s minds. How does you ensure this abstract descriptions you wrote for the other ' s requirement is not the forgetten while the other ' s minds is f Orgetten? God can ' t do it. God should not swamp into paradox himself. And then, what about it was others to see your code. He (or She) knew nothing on scene client commited requirements. How does he (or she) understand the unfathomable abstract description you wrote? " Hum, I coded according to Niubility method from XXX. If you are master X language, you can understand them easily. "And you might say. Oh my God. What do you know said? You should know this devergence exist in nature language understanding to be limited human ' s intelligence. How do you ensure it shouldn ' t hapPen in such abstract description? I ' m afraid creators of these computer languages can ' t say that. That's why the all computer language reserve annotation function.

So, you should discard ego and pigheadedness if you admit is human. You must face up to human weakness and write anotation in earnest.

2. Annotation simplifies code understanding

Sometimes, you maintain code for someone else, and you need to fix the bug. At this point, you need to read other code to help you find the bug. When you identify that the problem is not the result of other code, you simply need to understand the logical structure of the other code without having to read it verbatim. At this point, a well-commented code will speed up your work. Even if you just need to read the comment on the head of a function or method, you can do this step. After all, it's much easier to read natural language in annotations than to read the clearest code. This kind of comment is so for others, it is not convenient for themselves? Is there any reason not to write about it?

For the process of taking over other people's programs apes, sketchy's comments accelerate the understanding of the entire project code, will be quicker to complete the handover work, for the latter quickly into the role, to complete the his soporific-like project manager's requirements, is boundless beneficence. This is why the program apes abhor the code that no one else is commenting on.

In short, do unto others come back haunting. When you are not writing comments for others ' code, think hard about how you do it. Do you have any prejudice to writing comments? If not, congratulations, you have accepted this hard rule: All code must write comments. Well, how to write sketchy, concise comments beyond the scope of this article.

2.Anotation Simplify understanding

Sometimes 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 don't to come from these codes, you just understand logical structure of these codes WHI Ch Not read them word for word and sentance for sentance. It shoud speed up your work at this time. You could 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 do not write them?

Anotation concentrate on the main, point, speed, understanding whole project codes for the programmers takeing up and other ' s Work. It ' s eariler to finish the work takeing up from others. The benifits is beyond that the latter work on role as soon as possible to finish the pressing task from PM. This was why coding monkeys extremely detest the codes has not anotation.

Anyway, do unto others as you would is done. You should consider how does you do seriously if you complain the other ' s codes without anotation. Does you have a prejudice for writing anotation? If not, congratulations on already accept the following preremptory rule: Any coding and any anotation. Well, how to write plain anotation concentrate to main point, it's out of range of this article.

*written by Wayman qi*

Why writing comments must be a hard-coded standard for coding (bilingual original)