The habit of writing code determines your future-the sorrow of codoon

The results of these days have been quite big. Due to a problem with a project, when many people click it, they will crash or crash to the customer's desired results, and then they will not be able to find the error, as the customer was so busy, it was necessary to complete the process quickly, so he came to the Senior brother to help solve the problem.

The Senior friend also said a sentence when he got to the meeting. Add a comment first. Then add comments to the previously written code. What does each function segment do? After adding the comments, the Senior Engineer will solve the problem in a short time.

Because the project can run, but many people click, for example, when many people log on to the project at the same time, the project collapsed. The last reason is that static methods are used.

What I want to say here is why I did not find it at first, but added a comment, which will be solved in a short time. This introduces a typical "codenon ":

Kenong

Coding farmer (s): A group that relies on code writing for a living. It is characterized by low income and long working hours.

There may be many reasons for this problem. What I want to talk about today is that the habit of writing code directly affects your work and your income. Okay, I admit I 've seen a similar situation around me. So today, I wrote this article to explain that the code you wrote has no comments.

The code you write is intended for others.. Many people think that the machine that writes the code can run and it will be okay. The attitude of the post-event occurs: "It's okay. You just need to find someone who you want to find. Just don't look for me ." Why is it difficult for many people to read their own code? What I want to say is, who will cooperate with you in such an attitude and style, as soon as you leave, the company will be closed. Because someone else can't move your code. If you want to see it, you can just write it in a row. But maybe the code is not standardized yet. Then, it's silly to write it. It's better to rewrite it. Even if you can understand the code you write, it is not for yourself, but for others.

Without good document communication, it will waste a lot of boring time. For example, if you write c ++ and I write Java, it is difficult to interact if we do not have a uniform document for communication. Another point to note is that the code you wrote did not complete the task for this permit. The code is not written to run on the machine.

The maintenance in the later stage is actually a project. The maintenance in the later stage takes much more time than the time spent on writing code. This is what we have repeatedly stressed, why do I write more comments than code? A good habit is that comments account for 2/3 of the total length. In this way, the maintenance personnel can perform well maintenance or upgrade during the later maintenance of the project.

In fact, you can also think about it from another angle. If you don't have any comments for a project, you may be asked to make a mistake or perform later maintenance; I think you have all the emotions you want to cry. No one is willing to read the code without comments. Reading ancient texts in high school is a time-consuming way. If you have to read a word or a word, you have to read the comments below the ancient texts. Of course, that is the crystallization of culture. What is the crystallization of your code without comments?

Don't say that the time is not enough. If the project is too tight, no comments will be written. If there is no rule that the project is too tight, no comments will be written. If you do not write comments, it is a dead end.

Share with you:

13 suggestions for writing program comments

1. Comment each level (comments of each level have a unified style)

Annotate each code block, and use a unified annotation Method on each level of code block. For example:

• For a class, it should contain a simple description, author, and the latest change date.
• The method should contain the description, functions, parameters, and return values of the purpose.

It is very important for a team to use unified annotation rules. Of course, it is more recommended to use annotation conventions and tools.(For example, C # xml or Java javadoc), Which makes comments easier.

 

2. Use paragraph comments (comments for paragraphs)

Divide the code block into several "sections" that complete the independent function, add comments before each "section", and explain "what is going to happen" to the reader ".

// Check that all data records

// Are correct

Foreach (record in Records)

{

If (Rec. checkstatus () = status. OK)

{

...

}

}

// Now we begin to perform

// Transactions

Context CTX = new applicationcontext ();

CTX. begintransaction ();

...

 

3. Align comments in consecutive lines (align comments)

For multi-line code with suffix-based comments, you can edit the comments to align each line of comments to the same column.

Const max_items = 10; // maximum number of packets

Const mask = 0x1f; // mask bit TCP

Some developers use tabs to align comments, while others use spaces. However, because tabs are different in different editors or ides, it is best to use spaces.

 

4. Don't insult the reader's intelligence (do not insult the reader's IQ)

Do not write useless comments, such:

If (A = 5) // If a equals 5

Counter = 0; // set the counter to zero

Writing such useless comments will not only waste your time, but will also be easily distracted by your comments when you are reading such easy-to-understand code.

 

5. Be polite (Be polite)

Do not write impolite comments, for example, "note that stupid Users enter a negative number", or "correct the side effects caused by the poor and stupid coding of the original developer ". Such comments offend the author, and you don't know who will read the comments in the future-your boss, customer, or the poor and stupid developer you offend in the comments.

 

6. Get to the point (concise)

Do not write too much in comments, and do not write jokes, poems, or lengthy words. In short, annotations must be simple and straightforward.

 

7. Use a consistent style (consistent style)

Some people think that comments should be understandable to non-programmers, but some people think that comments only guide programmers. In any case, as stated in successful strategies for commenting code, what really matters is that annotations are always oriented to the same reader. At this point, they should be consistent. I personally think that I suspect that non-programmers will read the code, so I should locate the object of reading comments as a developer.

 

8. Use special tags for internal use (use special labels internally)

When processing code in a team, programmers should adopt a series of unified 'tag annotation' for communication. For example, many teams use todo to represent code that requires additional work.

Int estimate (int x, int y)

{

// Todo: implement the calculations

Return 0;

}

'Tag annotation' does not explain the code, but causes an idea or transmits information. However, when using this method, it is necessary to complete the information transmitted by 'tag annotation.

 

9. Comment Code while writing it (complete comments when writing code)

Add comments when writing code, because your thinking is the clearest at this time. If you leave the annotation task to the end, you have experienced two encodings. "I don't have time to comment" "I'm too busy" and "The project is delayed" are often reasons for not writing comments. Therefore, Programmers think that the most ideal solution is to 'write comments before writing Code '. For example:

Public void processorder ()

{

// Make sure the products are available

// Check that the customer is valid

// Send the order to the store

// Generate Bill

}

 

10. write comments as if they were for you (in fact, they are) Think of the readers of the Code as yourself (this is often the case in reality)

When commenting on the code, you should not only consider the person who may maintain your code in the future, but also consider that you may read the comments. The great Phil haack said: "Every time a line of code is knocked on the screen, you have to review the code from the maintenance perspective ." "As soon as a line of code is laid on the screen, you're in maintenance mode on that piece of code."(If you are famous, do not include the original sentence)

As a result, we are often the beneficiaries of our good comments, or the victims of bad comments.

 

11. Update comments when you update the code (remember to update the comments when updating the Code)

If the comment cannot be updated with the code update, it is meaningless to make the comment more accurate. The code and comments must be synchronized. Otherwise, these comments will be a torment for programmers who maintain your code. When using the refactoring tool to automatically update code, pay special attention to the fact that they will automatically update the code without changing the comments. These comments will naturally expire.

 

12. The golden rule of comments: readable code (readable code is the best comment)

For many programmers, one of the basic principles is to let the code speak on its own. Some may doubt that this is an excuse for programmers who do not like to write comments. However, this is indeed an indisputable fact. Self-explanatory code is of great benefit to coding, not only the code is easy to understand or even make comments unnecessary. For example, my article fluid interfaces shows what self-explanatory code is:

Calculator calc = new calculator ();

Calc. Set (0 );

Calc. Add (10 );

Calc. Multiply (2 );

Calc. Subtract (4 );

Console. writeline ("Result: {0}", Calc. Get ());

In this example, annotations are unnecessary and violate Tip #4. To make the code more readable, you should consider using appropriate names (as described in the classic ottinger's rules ), ensure correct indentation and code style bars (Code style bars are similar to # region # endregion, right ?). If this is not done well, your comments seem to be apologizing for obscure code.

You may also have some personal experience. Do you want to read the code without comments? Good habits determine your future.