// I have a comment -- Comments for Delphi developers (translated version)

 

 

Abstract:Robert Kozak, from Delphi R & D, discusses the correct coding methods.

// My comments By Robert KOZAK (Delphi R & D) Two months ago, I had the opportunity to review some of the code I wrote when I first worked for Delphi. I really don't want to admit that it was written by me-it's really bad. This is of course a humiliating experience. My technology has made great strides since that time. In fact, I noticed my changes over the past few months. I wonder if you have looked back at the code you wrote six months ago. I bet your mind must be "what am I thinking? I certainly won't write it like this ." If you had to maintain the code of your previous project, I bet it would be quite painful. What's even more painful is that you have to maintain other people's code. The only way to alleviate this pain is to make the code well annotated. Note that I am talking about "good" comments. In fact, it is better to leave a comment without a comment. For example, let's look at the following code. What has it done? The above annotation does not make any sense, and it cannot tell you the functions of this Code. Is there any better? The trick to writing a good comment is to ask yourself why you want to write this comment. In your comments, do not try to write how code works, but explain why you want to write it. In particular, the comments you write will be simplified if they are the right ones. (* Annotation type *) Annotations are divided into five basic types. I will explain them in a descending order. Duplicate code This type of annotation only re-describes the code in another way, without any additional information. This annotation must be avoided. Explain the code This type of code is often used to explain a complex or skillful piece of code. Annotations of this type are easy to understand. They are helpful for rewriting this code. Mark Mark a piece of Temporary Information for yourself or other members in your group. Now the Delphi 5 compiler can recognize // todo comments. Initially, I used // rk, and a friend of mine used /// to mark the Code, which should be removed after the project is complete. Code function Overview This type of annotation defines the code functions in a short language. This is much better than simply repeating code, because it allows some people who are not familiar with your code to quickly browse your code. Describe the purpose of the code This is the intention to explain the Code. In other words, it is to explain why the code is written like this. This type of annotation is easy to read and provides the necessary information for understanding the code. {Annotation method} Well, now we know that the last two types of annotations should be used (summary of the code and description of the Code purpose ). Let's look at some technologies that can be used properly. There are five basic areas to note: there is only one line of code, code segment, data structure, functions, units and projects. Only one line of code If you want to write a good comment (this is our purpose, isn't it ?), Only one line of code can use two annotations. First, this line of code is complex and needs to be explained. Although it is easier to rewrite a complex function to clarify its intent, it is difficult for a line of code. Second, there is an error in this line of code. You want to record it for later modification. I usually comment a line of code immediately after it. As follows:

This method is generally evolved into repeated code because there is not enough space to clarify the intent of the Code. It also tends to use acronyms because it is difficult to maintain code arrangement and alignment. The only applicable purpose is to interpret data declarations, maintain comments, or end tags of a piece of code (such as // end if, // end while, etc ). The data declaration should be as short as possible because it can leave more space for comments. If such a comment is added to each data declaration, it is difficult to maintain the consistency of the data declaration. Maintenance comments should be kept as short as possible, mainly recording the initialization information, data, and error count. Generally, it is not really the intention to annotate the code, so this method (followed by the Code) is more appropriate.

Code segment

This is the most commonly used (and best) method to annotate your code. In this way, you need to describe the intent of the Code clearly. Do not forget to concentrate on "why" rather than "How to do it ". This type of annotation should explain what to do next for the person who reads it. They can clarify what the code is doing through the annotation.

Data Structure Declaration

The comments here are used to describe the declaration of variables and the things that cannot be expressed by describing the names of variables. For example, the unit of the variable (kilometers, feet, lbs, etc ). Variable annotations should appear in the declaration of variables. If you have some flag bariables, each of them has a different meaning, they all need annotations.

Function

Some people will tell you that every function requires a huge unified style comment, which is really ridiculous. Simply put, this will make comments hard to read and far from the code it describes. A good comment should be near the code it describes, and generally a few lines are enough. If you need to take into account the details of the function, you need a little more details. See the following example:

I often have trouble with this code, because I always forget which one is sender and the other is target. Even in my own code, in functions with such sender and target, I will still forget which is the imported variable and which is the exported variable. Adding comments here can greatly reduce this confusion. Others can be included in the function comments (if needed): interface assumptions, modification history, function restrictions, global effects, algorithm sources, and design patterns used.

Units and projects

Finally, we discuss units and projects. When commenting on a unit or project file, you can describe the purpose of each file in a short language, or include the modification history, description of the main object, and the design pattern used. You can also include your name and contact information (phone number or email), so that if someone maintains your code, they can contact you. In addition, if you have any copyright information, you can add it.

// End file

If you think what I said makes sense, you should improve the annotation writing skills. Writing comments is not a difficult and time-consuming task. Remember, the Code explains "how to do", and the comment explains "why ". If you can keep this in mind, I think I can even understand your program.

{Todo: For more information, see code complete by Steve McConnell, Microsoft press}