Summary: Robert Kozak, from Delphi R & D, discussing the correct code writing method.
// My comment by Robert Kozak (Delphi R & D) I have the opportunity to review some of the code written for the first time when working for Delphi. I really don't want to admit that it is written - because it is too bad. This is of course an experience in humiliating. My technology has had a great progress since then. In fact, I noticed my change in these months. I don't know if you have come back to see the code you write half a year ago. I have to bet, you must "what I am thinking about? I am not thinking about it." If you have had to maintain the code of the previous project, I will be a painful. More painful is that you have to maintain code from others. The only way to mitigate this pain is that the code has a good annotation. Note that I am talking about "good" comment. Wild comments are not as good as notes. For example, let's take a look at the code below. What did it do? There is no significance of this comment above, it can't tell you the function of this code. Is there anything better? The trick to write a good comment is to ask why you want to write this comment. In your comment, don't try to write how to write code, but to explain why you want to write it. In particular, if you write the comment, if you go to the road, they will be very streamlined. (* Type of Comments *) Note 5 basic types. I will explain the type of comment on the type of duplicate code according to the difference to a good order, just re-describe the code with another way without any additional information. This annotation is absolutely avoided. Interpretation of this type of code is often explained to explain a complex or tactic code. This type of annotation is relatively easy to understand, and they are generally more helpful for overwriting this code. The tag tag is generally a temporary information for yourself or other members in your group. Now Delphi 5 compiler identifies // Todo comments. Initially, I used // rk: and my friend used to mark the code, which should be removed after the project is completed. Announcement of Code Features This type of comment is based on a short language concept. This is much better than just simple duplicate code, because it allows someone who is not familiar with your code to quickly browse your code. This is the intention of explaining the code, in order to explain why this is written. This type of annotation is easy to read and provides the necessary information for understanding code. {Note method} Good, now we know the two types of annotations should be used (code summary and description code purpose). Let us see some technologies that can be properly used. There are 5 basic areas where you can use a comment: only one line of code, code segment, data structure, function, unit, and engineering. Only one line of code If you want to write a good comment (this is the right thing is right, isn't it?), Then only two comments can be used in only one line of code. The first, this line code is complicated and needs to be explained. Despite rewriting a complex function to clarify its intent, it is difficult for a line of code. Second, this line code has an error, you want to record it in order to modify. I usually will be commented next after a line of code. Just like this:
This method is generally evolved as a repetition code because there is no sufficient space to clarify the intention of the code. It is also because it is difficult to maintain the alignment of the code and to tend to use an abbreviation. The only suitable use is to interpret data declarations, maintain annotations or end tags of a piece of code (such as // end if, // end while, etc.). Data declarations will be as short as possible because of this annotation, because this can be accounted for. If this annotation is added to each of the data declarations, it is difficult to maintain the coherence of the data declaration. Maintenance annotations generally should be as short as possible, mainly to record initialization information, data, and error. It is generally not a true comment code, so it is appropriate to use this way (followed by the code). Code segment This is the most commonly used method (also the best) one way to comment your code. In this way, you should describe the intent of the clear code. Don't forget, you have to focus "why" instead of "how to do". This type of comment is to read what you want to do, what can they make a clear code by comment. Data structure declaration
The comments here are used to describe the variable declarations and what cannot be expressed in the name of the description variable. For example, units of variables (km, feet, pounds, etc.). Variable annotations should appear in a variable declaration, if you have some marg bariables, each of them has different meaning, then they all need to comment. function
Some people will tell you that every function requires a huge unified annotation, which is really ridiculous. Simply, this will make the comment hard to read, and the code it will be very far away. Good comment should be near the code it described, and it is sufficient to say a few lines. If you want to take into account the details of the function, you need a little more details, see the following example: I often encounter trouble on this code, because I always forget which ofsers are Sender which is Target. Even in my own code, in a function with this Sender and Target, I will still forget which one is the imported variable, which is the exported variable. Here, add notes can alleviate this confusion to a large extent. There are other options that can be placed in the function comment (if needed): Interface envisage, modify historical records, limitations, global impact, algorithm sources, and design modes used. Unit and engineering
Finally, we discuss units and projects. When a unit and engineering file comment, you can describe the purpose of each file with a short language, or you can include modifying history, the description of the main objects, and the design modes used. You can also include your name and contact (phone number or email), so if someone maintains your code, they can contact you. In addition, if there is copyrighted information, you can also add it.
// end file
If you think I said, you should improve the skills of writing a comment. Write a comment is not a difficult and cost-effective thing. Just remember, the code description "How to do", and the comment description "Why". If you can always remember this, I want to even understand your procedure.
{TODO: More information, please see Code Complete by Steve McConnell, Microsoft Press}
