Knowledge Base - To Comment or not to Comment, That is the Question
To Comment or not to Comment, That is the Question
One of the things I see with most programmers is the lack of comments in source code. I am guilty myself of lapsing in this department, and I have often looked at my code some time later after I have written it and have wondered what I was thinking when I wrote such-and-so. I haven't commented the examples in the lessons much since I didn't want the comments to confuse the actual source. However, in an actual script, comments are a must.
It is quite easy to look at a script that has just been written and to figure out what that script is supposed to do. However, when that script is reviewed again in a month or six months, it may not be all that apparent. Comments allow both the script writer and someone else, to get the drift of what was in the mind of the script writer when the script was written.
Comments also allow for additional information to be added to a script, that does not directly relate to the actual script itself. For example, a team of level designers are working on a project and each level designer is going to be adding his or her own scripts. How is it determined who wrote what? This can be critical if more than one person worked on a particular map. By adding a header comment to the scripts that list information like the author (s), the email address, the date last modified things like debugging and testing become much easier.
Comments do not add any overhead to the compiled code. Virtually all compilers strip out comments from the compiled code. The engine doesn't give a flip for comments, these are only a convenience for the script writers.
ACS has two types of comment operators: /* .. */ and //. The first set is used to comment a block of text, and the other is used to comment a line of text.
/* This will comment out
a block of text. */
// RDC (05/02/99): This will comment out a line of text and indicates who made the change and when.
Keep in mind that anything inside the block or the line will be treated as a comment, so do not place any executable code in the comments.
The following is a suggested header comment to illustrate what a header might look like if working on a multi-author project.
/* Author(s):
Email:
Email:
Date last modified:
Log of Changes
Date: Who: Comment:
*/
Use comments liberally, even if they seem trivial. They may be trivial at the moment, but they won't be a month or six months later when trying to debug a section of code. They do take time to write, but the investment will pay dividends.