During a development meeting, there was a debate about whether code comments were needed.

The main contents are summarized as follows:

A: I suggest that projects should have comments. Some of our programmers almost never comment code. We all know that uncommented code is unreadable.

B: I don’t think comments are necessary. Comments are supposed to be a panacea, but anyone who has actually written code knows that comments make code harder to read. Annotations can easily generate a lot of nonsense, and coding languages are much more concise.

C: That’s right. If the code isn’t clear, how can it be commented clearly? Besides, comments are out of date every time the code changes. If you misread an outdated note, you might end up in another hole.

In addition, overcommented code is harder to read, which increases reading. Why read a bunch of comments when you already have a bunch of code to read?

A: Everything the editor needs to know is in the code? In a binary file? What’s the point of arguing about comments?

B: I object to comments mainly because I think they are a waste of resources.

D: Not really. Annotations can be overused, but they are wonderful when used well. Also, in my work experience, I have maintained both commented and uncommented code, and I personally prefer to maintain commented code. One final note: Although there is no need for a standard for annotation, I do recommend that you annotate your code.

.

The discussion about whether to add comments lasted for a long time, and finally we reached the following decision:

“Annotation is encouraged, but not abused. We have Code Review as part of the development process, so everyone knows what a good comment looks like, and when you have a bad comment, you need to tell them how to improve it.”

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.

The main factor that matters 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 minimal complexity of control flow and data structures.

After the meeting I reflected: Was the comment really repeating the code in a verbose way, so it didn’t work?

A good comment is not about repeating code or explaining code. It makes the author’s intent clearer.

Daily notes

In general, it’s easy to write bad comments and hard to write good ones. Bad comments just don’t help.

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 i=0; i<num; i++){ System.out.Println("Sum = " + sum); sum = current + previous; previous = current; current = sum; }Copy the code

In fact, this code evaluates the first num of the Fibonacci sequence. Blind faith in annotations can go the other way if they’re wrong, but good annotations can get you twice as far.

// compute the square root of num using the Newton-raphson approximation r = num / 2; While (abs (r - (num/r) > how) {r = 0.5 * (r + (num/r)); } System.out.println("r = " + r);Copy the code

In the above example, it is used to calculate the square root of num.

Purpose of comments

The primary purpose of writing code and comments is to help people understand the code and understand the author’s intentions.

So good code is self-explanatory, and only consider writing comments if the code itself doesn’t make it clear what the author intended.

That is, comments should express why my code does what it does, not what my code does.

A large part of the reason we introduce so many design patterns, frameworks, and components into our software development process is to improve the readability of the code.

Programming languages, especially high-level programming languages, are themselves the language of communication between humans and machines. Languages themselves are required to meet human readability and to use expressions consistent with our natural language without additional comments.

How do I write the comments?

Of course, good code > bad code + good comments, good comments are valuable, bad comments waste time and can be harmful, self-explanatory code is best.

Of course, good code > bad code + good comments, good comments are valuable, bad comments waste time and can be harmful, self-explanatory code is best. Good comments do not repeat code or explain it, but make it clearer. Comments explain what the code does at a higher level of abstraction than the code itself.

Specific operation means include but not limited to the following:

  • Annotate appropriately, weigh carefully, be neither obscure nor superfluous;

  • Note that there are changes, need to update in time;

  • Some tricky or special business logic in commenting code that would otherwise confuse the reader;

  • If the address of jIRA, bug, requirement, etc. helps you understand the code, add it appropriately;

  • If your code is well named and structured, you generally don’t need comments. But a one-sentence explanation of intent and functionality is great, because many times it’s faster to read a single comment than to parse dozens of lines of code just to understand how it works.

Principles of annotation

1) Notes should follow Occam’s Razor: Don’t add substance if you don’t have to

Poorly written and maintained comments (such as code changes without comments) can make code less readable.

2) There is a saying “code as comment”, which is not quite true, but makes sense

When code is written well and beautifully, comments can be refined and will inevitably be easier to understand. In addition, it is much more important to write clearly the idea (difficult, critical) than the Author, Date. Catch the important information.

3) Try to write why rather than what you did in your comments

What did you do? Just look at the code. The code doesn’t lie. But why it’s written like this is sometimes very confusing. Maybe it is dealing with a corner case, maybe it is bypassing a system restriction, or maybe it is some strange requirement. This kind of code, without the context at that time, will be like Oracle in a few months, and will not know what it wants to do. If you don’t like it to optimize it, you don’t know where it will collapse.

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

conclusion

  • Good comments are valuable

Whether or not to comment is a serious issue. Poor comments are a waste of time. Good comments are valuable. Comments can be placed at: variable specific meanings and limitations, at the beginning of a responsibility block, at the beginning of a general control structure, at the beginning of a subroutine call, at the beginning of a method describing a function, at the beginning of a class describing a function.

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

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

  • Good code speaks for itself

If the code is so bad that it needs a lot of comments, try to improve the code until you don’t need too many comments.

  • Comments should say what the code can’t

Information such as an overview or meaning. The comments themselves should contain a concise abstract summary of the code, not implementation details of the concrete code.

  • The comment style should also be concise and easy to maintain

Some annotation styles require a lot of repetitive work and should be abandoned in favor of an easy to maintain annotation style.

This article was first published on my public account “The Road to Architecture Improvement” : A debate about code comments and three thoughts

Thanks for reading!