Some suggestions and views on commenting in scripts

Script

When you learn that a code technology is basically getting started, you'll naturally notice the importance of improving the quality of your code, while writing annotations is the first step to improving code quality-and probably the easiest one. Here are some tips for writing notes that I've summed up!

　　One, do not annotate for comment!

The main purpose of annotating your code is to improve the readability of your code, but there is a mental problem: if you think that you can improve the quality of your code by writing a comment, you can prove your strength, and that's not going to be easy.

I believe someone must be writing a note, do not grasp the correct mentality, which leads to the written comments are often inappropriate. What are the outdated notes? I have written this note:

......
' Open the Recordset and record all the data in the Orders table
Objrs.open "SELECT * from Orders", objconn,1,1
......
Objrs.close ' Close the recordset
Set Objrs=nothing ' Frees Recordset objects
......

You get it? This is one of the outdated annotations: formal annotations, which tend to be cumbersome to code, can even make the code less readable by highlighting where it really needs to be commented.

This is the reason why the mentality is not grasped well. If you can grasp the attitude correctly, you will put your mind to improve the readability of the code, rather than put it on the write note! Writing comments is just one way to improve the readability of your code, and writing comments is also about skill and efficiency. This is discussed below.

　　 Second, the comment of the rubbish is not good annotation!

In my opinion, good naming conventions and code formats tend to improve code readability more than annotations. Naming conventions can explain the role of code elements, and code formatting can make programming ideas clearer--but unfortunately, they don't always jump out of the loop of code and do not have a strong description of the code, so we still rely on annotations.

Therefore, we should first be strict with the naming convention and code format two aspects, and then to describe the code as an auxiliary annotation. Don't doubt, do you read the code first or look at the annotation first? In general, the questions that the code can clearly articulate do not need to be commented on, such as the spam comments written in the 1th above, and no one will take them seriously (but it's good to see the example in the introductory tutorial). There are, of course, exceptions to the comment that the code mainly describes the means of the situation in the 3rd discussion.

What kind of annotations are timely? In the right place, it is timely to write notes at the right length. I can not give you more specific answers, but the direction has been pointed out, you need to do is to think, reference, think again ... In short, making annotations as simple, elegant, and effective as code is the goal, so that code can improve the readability of the code!

It is not enough to be timely, if the comments are ambiguous, still not good comments! Therefore, it is equally important to make annotations more accurate in describing the code, especially for functions/procedures, and the nature of the code snippets. By yesterday's article (Did you take a shortcut?) --one of the two processes mentioned in the two VBS process--getrandom--, for example, is a description of my role: Returns a new array that consists of randomly extracting a specified number of distinct elements from the source array. If you were to describe its role, how would you describe it? Please don't get me wrong, I'm not puff, I just took a recent example from myself.

In short, good notes, to be timely, but also accurate and effective! Otherwise, it's better not to write.

　　 third, external documents are often more effective than internal annotations!

You may be surprised that I have highlighted the function/process and tip of the nature of the code snippet comments to be accurate, why I did not mention the comment on the class? The individual thinks that if the program uses a design method that is oriented to (or based on) the object extensively, the annotation of the class should be considered in a long-term way. One of the things is that if the class needs to be encapsulated, the annotation is only valid at design time, there is little point in improving the readability of the Code; the second is that class design and use should be macro-grasp, and the comments in the code is often microscopic description, it is difficult to achieve the effect of macro-description, such as a lot of graphs to describe the class relationship, The annotation is not working as a result.

This time, we need to have an external document! Don't ask me what an external document is, how to write an external document. In short, everything you can do to improve the readability of your code.

There is another question to be asked when to write notes and documents. Some people write the code first, then take advantage of the comments before they forget, some people first write the design draft, and then start writing code ... In fact, there is no right or wrong, to achieve the goal is good. --note, rational co-ordination of formal project development is not in the scope of the discussion, this development to consider too many factors, not so casual.

　　try to avoid client comments!

The only downside to client annotations should be increased I/O pressure, right? If you add comments for HTML and client script, the subjective estimate will add 1K bytes to each page, and now the rest is to estimate page traffic ...

Why add annotations to client script and HTML? Especially for HTML annotation is difficult to understand--or maybe I did not see it, hehe. Standardized b/S client design pay attention to the structure, presentation, behavior separation, I think this is the best comment on client code?

　　review and improve the comments in the previous code!

Writing notes is also largely to prevent you from reading the code later on, so if you can constantly review and improve the comments in the previous code ... Oh, or not to say it, I believe that people use their knees to understand the benefits of it. --How do you feel that my article is a cop-out?

Finally, I wish all the special feelings of good luck!