Career norms-Comment

Zookeeper

The system has been knocked out in the past two days, and the overall debugging has been completed. During the debugging process, a major problem has been found, that is, your own annotations are not enough, sometimes I don't understand what the U-layer event is, sometimes I don't know what parameters the event is passing, and sometimes I don't know what the corresponding B-layer and D-layer are, what did B and d do ,............. So sometimes you need to read the code from start to end, to see what parameters are passed, to see what these parameters are used for, and to see, the corresponding layer B processes the returned data and looks at the corresponding layer D.

At this time, this process is really a waste of time, so you may feel bored. This is your own code. You can write and debug your own code. If you want to debug other people's code like this, what else should you feel like ?? Are you going to vomit ??

So in this small program, I deeply realized the importance of code comments.

I thought about why I didn't write comments at the time, combining the lessons that my previous teacher taught me. I sorted it out.

① Writing comments is too time consuming.

In fact, it does not take much time to add comments when writing code. At that time, it was a hot hit, and I had a better understanding of those codes. Writing a comment is just a few words. However, if you add comments later, you should not only repeat those words, but also understand the code and related code. If you do not acknowledge the comments later, the debugging process will be the same as described above.

② Some processes are difficult to comment out.

Generally, if a part of the code is difficult to comment out, it is more difficult for others to understand your code without commenting. I don't know how to make others understand it clearly.

③ Complicated and difficult-to-Comment Code may not be good code. If you find it difficult to add comments to all or part of the process, take a look at your code and you will find a better solution.

Therefore, comments are not an accessory to the Code, and they coexist with the code.

 

Annotations are the explanations and descriptions of the Code. The purpose is to make it easy for others to understand. In order to let others know what this code is. There are several types of code annotations

(1) end comment

Is the comment at the end of each line of code. These annotations can only be used for short descriptions, such as variables.

② Internal comments

Internal annotations are the most common and important annotations. Internal annotations can be used to describe the implementation method of the process, so that the reader can smoothly go through different turns. For example, if statement, select case statement, loop statement, global variable, and important variable. Internal comments are helpful for understanding the code.

③ Comment header.

Add comments to the first line of the module, class, attribute, and method to prompt the user when calling. The comment header can contain multiple text items, such as input parameters, return values, original author, programmer who finally edited the process, last modification date, copyright information, and even colors that programmers like.

Each comment header should have a uniform format, which has been standardized in our net code specification.

 

Of course, in order to make our comments not look messy, we can enhance the readability of the comments.

① Easy to understand ----- comments are for people to read, rather than for computers to read. Annotations should be easy to understand. It is better not to write comments that are hard to understand.

② In addition, annotations are text information. (Translated in Chinese and spoken in your own words) --- just as the text information of an application must be clearly written, code comments should also follow good writing rules. For example, use a relatively complete statement to describe it. Do not use abbreviations.

③ Writing --- comments are usually located at the beginning of the Code to be explained. To visually highlight the relationship between the annotation and its code, indent the annotation so that it is at the same level as the code.

 

I have already written the annotation types and the format of the annotation. So what should I comment on?

Type	Description
Class, process, and Method	Describes its purpose (rather than its implementation method), parameters, and return values.
Input	Function of the input parameter
Output	Description of the value returned by the process and its meaning
Variable	In particular, global variables are used

The types of these annotations should be added in the Code. If there are any deficiencies, please note.

 

Use text to describe the role of the code and simply repeat the code to do something. Such comments can hardly add any information to the Code. (This sentence doesn't seem quite understandable)

Annotations make the code easier to understand and trace. Excellent comments are like a good design blueprint that can guide readers through the twists and turns of your application to explain the expected running results and possible exceptions.

Of course, I still haven't reached this level. The more I write, the more I don't understand. Ah ................

 

 

Career norms-Comment