Avoid writing comments in code

If you use a lot of comments to "Decorate" the Code is a good thing, adding a large part of comments to the code is a icing on the cake. Is that true? In fact, this is not exactly the case. If you are too late, good intentions will also do bad things.

'*************************************** **********
'Name: copystring
'
'Purpose: this routine copies a string from the source
'String (source) to the target string (target ).
'
'Algorithm: It gets the length of "Source" and then copies each
'Character, one at a time, into "target". It uses
'The loop index as an array index into both "Source"
'And "target" and increments the loop/Array Index
'After each character is copied.
'
'Inpututs: input the string to be copied
'
'Outputs: output the string to receive the copy of "input"
'
'Interface assumptions: None
'
'Modification history: None
'
'Author: Dwight K. coder
'Date created: 10/1/04
'Phone: (555) 222-2255
'Ssn: 111-22-3333
'Eye color: Green
'Maiden name: None
'Blood type: AB-
'Mother's maiden name: None
'Favorite car: Pontiac Aztek
'Personalized license plate: "Tek-ie"
'*************************************** **********

I often do not read comments written by developers. It seems that they do not understand, but their code has already told me that it isWhatWork; what we need to note is that the programWhy?Work in this way. Code comments have been widely misunderstood and abused, so that you are beginning to doubt their original values-is there a need for comments? What are you expecting? Be careful! Here is a piece of code without any comments:

R = n/2;
While (ABS (R-(N/R)> T ){
R = 0.5 * (R + (n/R ));
}
System. Out. println ("r =" + r );

Do you understand what this code will do? It looks clear, but what is it?

Let's add a line of comment:

// Solve the square root of N using the Newton-laferson Approximation
R = n/2;
While (ABS (R-(N/R)> T ){
R = 0.5 * (R + (n/R ));
}
System. Out. println ("r =" + r );

This should be what I want. Isn't it? It seems like a good compromise between the two extremes of writing an epic comment without any comments at all and every line-Are you satisfied?

Not necessarily! Instead of adding comments, I prefer to re-construct the Code as follows:

Private double squarerootapproximation (n ){
R = n/2;
While (ABS (R-(N/R)> T ){
R = 0.5 * (R + (n/R ));
}
Return R;
}
System. Out. println ("r =" + squarerootapproximation (R ));

I didn't add a line of comments, but this piece of mysterious code is now very easy to understand.

Although comments are not good or bad, they are often used as "crutches" to support code ".You should always focus on writing code, and forget to note the existence of such things.This forces you to write your code in the simplest, most straightforward, and most self-explanatory way.

To make it easier for your programmers to read and understand your code, if you have already rewritten, restructured, or even re-designed your code many times-when you have nothing to do, you have no idea of any way to make your code easier to understand-at this time, you should add some annotations to explain what your code is.

As Steve yegge pointed out, this is a key difference between junior developers and senior developers:

Frankly speaking, if I had read too much code before, it would have caused me to crash and its complexity had exceeded the limit I could accept. When I have to continue working on the basis of those codes, I usually rewrite them, or at least write a lot of comments. Now, when I encounter this situation, I will quickly pass through without complaining. When I have a clear goal in my mind and a complicated piece of code to write, I will spend time implementing the Code instead of (using annotations) write down its story and tell it to myself.

Junior developers rely on Annotations to tell stories, but actually they should rely on the Code itself. Annotations are "narration" and they have their own values, but they must not be used to replace (in the story) plots, characters, and scenes.

Perhaps this is the secret to comment out the code:To write a good comment, you must be a good writer.The annotation is different from the code. It is not for the compiler. Annotations are words used to communicate ideas with other humans. Although I have a good relationship with (MOST) programmers, I must admit that effective communication with others is really not our strength. I have received an email from a programmer in our group. There are only three emails in it, but I am confused. Can we believe that such a person will write clear and easy-to-understand comments in the code? So I thought, maybe it would be better for some of us to do what we are good at -- that is, to write code for the compiler, and to write it as clearly as possible, however, it is impossible to use annotations as the final solution.

It is difficult to write good and meaningful comments. Like writing code, it is an art. It may be more artistic! As Sammy Larbi says in the article "common excuses used tocomment code and what to do about them" (common excuses for commenting on code and solutions, if you think your code is too complex and hard to be understood without comments, it can only mean that your code is poorly written. Rewrite your code until it no longer requires any comments. If you still think that annotations are necessary after these efforts, add comments as much as possible. Remember, be careful!