Shulou(Shulou.com)06/03 Report--

This article introduces the relevant knowledge of "understanding about code comments". In the operation of actual cases, many people will encounter such a dilemma, so let the editor lead you to learn how to deal with these situations. I hope you can read it carefully and be able to achieve something!

At an R & D communication meeting, there was a dispute about whether code comments were needed or not.

The main contents are summarized as follows:

A: I suggest that the project should have a comment. Some of our programmers almost never comment on the code. Everyone knows that uncommented code cannot be read.

B: I don't think comments are necessary. Comments are used as a panacea, but anyone who has actually coded them knows that comments make the code more difficult to read. Comments are easy to generate a lot of nonsense, while the coding language is much more concise.

C: that's what happened. If the code is not clear, how can it be commented clearly? Besides, when the code changes, comments become obsolete. If you misread outdated notes, you may step on it again.

C went on to say: in addition, code with too many comments is more difficult to read, which increases the amount of reading. There's already a lot of code to read, so why read a lot of comments?

A: everything the editor needs to know is in the code? In the binary file? What's the point of arguing about the value of notes?

B: I object to the comments mainly because I think it's a waste of resources.

D: it's not fair to say that comments can be abused, but comments are wonderful when they are used well. In addition, in my work experience, I have maintained both annotated and uncommented code, and I personally prefer to maintain annotated code. Finally, I would like to add: although there is no need to set standards for comments, I still encourage you to comment on your own code.

.

The dispute over whether or not to add notes was discussed for a long time, and in the end, we agreed on the following decision:

"We advocate commenting, but don't abuse it. There will be a Code Review process in our development process so that everyone will know what good comments are like, and when you encounter bad code comments, you need to tell him how to improve them."

Problem thinking

As a research and development student, I am no stranger to code "comments". It often exists as a special supplement to our code documentation.

In fact, the main factor in code documentation is not comments, but good programming style.

Programming styles include good program structure, easy to understand methods, meaningful variable and subroutine names, constants, clear layout, and lowest complexity control flow and data structures.

After the meeting, I was thinking: is the comment really repeating the code in a verbose way, so it's useless?

A good comment is not about repeating the code or interpreting the code, it will make the author's intention clearer, and the comment should explain what you want to do in a higher sense.

Daily notes

In general, it's easy to write bad notes, but it's hard to write well. Poor comments will only be unhelpful.

Let's look at a few examples:

/ / write out the sums 1.. n for all n from 1 to num current = 1; previous = 0; sum = 1; for (int iTuno; I TOLERANCE) {r = 0.5 * (r + (num/r));} System.out.println ("r =" + r)

The above example, it is used to calculate the square root of num, the code is general, but the comments are more accurate.

The purpose of the comment

The first purpose of writing code and comments is to help people understand the code and the author's intention.

So good code itself has a self-explanatory function, and comments are considered only if the code itself cannot clearly state the author's intentions.

That is: comments should express why my code did this, not what my code did.

Our software development process introduced so many design patterns, frameworks, components, the development process developed so detailed design specifications, coding norms, naming norms, a large part of the reason is to improve the readability of the code.

The programming language, especially the high-level programming language, is the language of communication between people and machines. The language itself is required to satisfy human readability, and it needs to be used in accordance with our natural language expression habits without additional comments.

How do you write the notes?

Of course, good code > bad code + good comments, good comments are valuable, bad comments are not only a waste of time but also can be harmful, self-explanatory code is best.

Of course, good code > bad code + good comments, good comments are valuable, bad comments are not only a waste of time but also can be harmful, self-explanatory code is best. A good comment is not to repeat the code or interpret it, but to make the code clearer and explain what the code is going to do at a higher level of abstraction than the code.

Specific means of operation, including, but not limited to, the following:

Note properly, weigh carefully, neither obscure nor superfluous

Note that there are changes that need to be updated in a timely manner.

Comment on some tricky skills or special business logic in the code, otherwise it will confuse the reader of the code

If attaching the address of jira, bug, requirements, etc., can help you understand the code, you can add it appropriately

If the code is well named and well structured, generally speaking, no comments are required. But it's also great to explain the intent and function in one sentence, because most of the time you just want to know how the code works, and reading a comment is much faster than analyzing dozens of lines of code.

Principles of annotations

1) the notes should follow the Occam razor principle: do not add entity if it is not necessary.

Poorly written comments and poor maintenance (such as changing the code without changing the comments) can lead to poor readability of the code.

2) there is a saying that "code is comments", which is not entirely true, but it makes sense

If the code is well written and beautifully written, the comments can be refined and must be easier to understand. In addition, writing down your ideas clearly (difficult and critical) is much more important than Author or Date. Grab important information.

3) it is suggested that what is written in the comments instead of what has been done.

What has been done, just look at the code, the code will not lie. But why it is written like this is sometimes very confusing. It could be dealing with a corner case, it could be bypassing a system limitation, or it could be some weird requirement, this kind of code, without the context at that time, in a few months, like Oracle, I don't know what I want to do. If you don't like it again, you won't know where it will collapse in the future.

In fact, most of the code should be self-evident and do not require comments.

Summary

Good notes are valuable.

Whether it should be annotated or not is a question that needs to be taken seriously. Poor comments are only a waste of time. Good notes are valuable. The location of comments can be as follows: the specific meaning and limitation of the variable, the beginning of a responsibility code block, the beginning of the general control structure, the call of the subroutine, the description function at the beginning of the method, and the beginning of the class.

The source code should contain most of the key information of the program.

As long as the program is still in use, the source code is more up-to-date than other materials, so it is beneficial to incorporate important information into the code.

Good code itself is the best illustration.

If the code is too bad and requires a lot of comments, you should try to improve the code until you don't need too many comments.

Comments should say what the code cannot say.

Information such as an overview or intention. The comment itself should contain a concise abstract summary of the code, not the implementation details of the specific code.

The annotation style should also be simple and easy to maintain

Some annotation styles require a lot of repetitive work, so we should abandon them and use annotation styles that are easy to maintain.

This is the end of the content of "understanding Code comments". Thank you for reading. If you want to know more about the industry, you can follow the website, the editor will output more high-quality practical articles for you!

Welcome to subscribe "Shulou Technology Information " to get latest news, interesting things and hot topics in the IT industry, and controls the hottest and latest Internet news, technology news and IT industry trends.