Glitchfinder
Staff
The spill-all guide to why commenting is something that actually helps you!
By: Glitchfinder
All right. So, most of us know what a comment is, even if we're not a scripter. For those who don't, it's that green text in the script window that doesn't actually do anything. Now, most of us also know that commenting is something that general programming standards recommend we do. Yet we never seem to comment anything. In this tutorial, I'll go over RGSS commenting, from the basics to the guidelines, and I'll show you how commenting isn't something that you should dread doing, because it's just that simple.
Why Should I bother Commenting?
Commenting is a very important piece of programming, and one that's sadly been neglected in the RM* community for some time. There are a multitude of reasons for using comments, and I'll go into some of them here.
Comments Can Explain Code
First and foremost, comments are intended to tell someone what a piece of code does. Not everyone is a good enough scripter to be able to read code like plain text, and someone might just be unlucky enough to try to learn from your code. While you may know what your code does now, if you come back to it a few months down the line, you'll probably have to go through the entire script trying to figure out exactly what you were doing. Comments make the entire process easier, by telling you what each line does in plain English. (Or whatever your language of choice is)
Comments Improve Format and Legibility
Comments are also a means of formatting a script, to make it easier to read. This is easily seen in the default RMXP and RMVX scripts, where every single script is given a small header that shows the name and use of the script. Not only that, but they gave every single block of code a method header, which makes it far easier to scroll through a script and find that one piece of code you were looking for. If you've ever looked at the same code, with and without method headers, you'll see that the headers really do make a significant difference.
Comments, Debugging, and You
Comments can also be used for debugging. Crazy as that may sound, it's true. You can use a comment to mark a place that you'll need to change down the line, or to block out a piece of code that's giving you trouble. If you're marking places for future edits, it's also recommended that you always use the same format. Usually, something like #fixme will do. If you always use the same comment, all it takes to find them again is typing ctrl+shift+f, and typing in the comment, exactly like you would if you were tagging something. (So, in my example, you would simply type in #fixme) When you click search, it will show every single time that text appears in any script in your entire project, which makes it a simple matter to go back to your markers and fix them.
Other Stuff Comments can do
Finally, comments can also be used for informative purposes. I'm sure some of you have noticed the truly massive headers on my scripts. While I'm not saying you should do the same, it is useful to know that you could use a comment header to tell people how to use your script. (In case someone ends up with the script, but not the original post with the instructions.) I also used the headers to tell people what they're allowed to do with my scripts (in essence, a license), and to inform them what they're expected to do if they use the script.
The Basics
All right. This part of the tutorial is for those of you who aren't sure exactly what a comment is, or what it does. However, it might also be helpful to some of you more advanced scripters, since it will cover a few details you might not know unless you actually comment on a regular basis.
First off, let's go over what a comment really is. A comment, in the most basic form, is something you type that the program will completely ignore. It doesn't matter what you type in the comment, because it will actually have no effect on the interpreter. However, one thing to note is that it does have a very, very slight effect on runtime. When you start up the program, the interpreter will load up your scripts. When it finds a comment, it will cut out everything until it finds the end of the comment. This takes basically no power, but if you did something dumb like make a 10,000 line comment, it could potentially have an impact on the speed that the game will open. Even then, a 10,000 line comment wouldn't have much of an impact on the interpreter.
Line Comments
Anyway, on to the real information. The most basic comment is the line comment. You place a line comment by typing the # character. Sounds simple, right? When you type # into the script window, it will be green, as will everything after it on that line. This is because everything that comes after the # symbol is actually a comment, and will do nothing. However, once it finds a carriage return, it will go back to actually reading the code. (They're also called line breaks. You press the Enter key to make them, remember?) This type of comment can be placed anywhere in a line, and anything before the # symbol will actually act as real code. Here's a couple examples of line comments from the default RMVX code:
Ruby:
#==============================================================================
# ** Scene_Equip
#------------------------------------------------------------------------------
# This class performs the equipment screen processing.
#==============================================================================
# Display when there are multiple members
PartyName = "%s's Party"
#--------------------------------------------------------------------------
# * Public Instance Variables
#--------------------------------------------------------------------------
attr_accessor :next_scene # screen for switch (String)
Block Comments
The next type of comment is called the block comment. (It is also referred to as the multiline comment) This is used to turn large chunks of text into a comment. This is most useful for blocking out pieces of code because they're causing trouble with the scripts, or because you wish to test something without that code. The block comment is a bit different from a line comment, however. With a block comment, you have to start and end it. (Admittedly, you do this with line comments too, but most people don't realize that they're actually ending those) To start a block comment, type =begin at the very beginning of a line. To end one, simply type =end, also at the very beginning of a line. Now, an important thing to note is that these actually have to be at the very beginning of a line. If either of these has anything in front of it, the game will crash due to a syntax error. Anyway, here's an example of a block comment:
Ruby:
<span style="color:#000080; font-style:italic;">=begin
<span style="color:#000080; font-style:italic;"> #--------------------------------------------------------------------------
<span style="color:#000080; font-style:italic;"> # * Termination Processing
<span style="color:#000080; font-style:italic;"> #--------------------------------------------------------------------------
<span style="color:#000080; font-style:italic;"> def terminate
<span style="color:#000080; font-style:italic;"> super
<span style="color:#000080; font-style:italic;"> dispose_menu_background
<span style="color:#000080; font-style:italic;"> @edit_window.dispose
<span style="color:#000080; font-style:italic;"> @input_window.dispose
<span style="color:#000080; font-style:italic;"> end
<span style="color:#000080; font-style:italic;">=end
But I Hate Commenting! What Should I do?
Well, you might like to know that many, many programmers hate commenting. The best solution I can offer is this: don't retroactively comment. If you comment a script after you're already done with it, it will seem like a massive chore, especially since you're going to have to figure out exactly what that strangely named variable does. You know. The one you made at the start and then forgot about half a dozen times. Instead, I recommend you comment as you go. My favorite method is to type out a line comment saying what I'm about to do, and then write the code that actually does it.
Now, if you do that, make sure you don't go overboard. Commenting things like end statements is rather pointless, no matter who you are. Instead, if you see some lines that could be grouped together, precede them with a single comment explaining them as a group. I do recommend that you comment if, elsif, and else statements, however. This is because you can use the comments to explain the conditions in better detail. I also recommend you make a comment saying what a returned value actually means. Instead of saying something like # Return true, try saying # Return that the character's armor was changed. (Or whatever your return value actually means.)
Finally, don't be afraid of extending a comment to a second line if you need more space to explain something. You're better off with an easy to understand script than with one whose comments are so short and cryptic that it confuses someone even more.
One Last Note
As I've explained earlier, the primary purpose of comments is to make a script easier to read and understand. However, if you're commenting out code for any reason, you should never, ever leave it as a comment when you actually release the code to the public. This is because such comments not only reduce the readability of a script, they can make it downright confusing. If your script has configuration options that are commented to keep them from being active, you're not thinking like a true programmer. Instead of forcing check after check to see if a variable actually exists, just define it at the start, even if it's simply to say that no, this option isn't being used. The variable could be as simple as true/false, so long as it always exists. This makes errors less likely, and at the same time, it makes it more clear what is and isn't code.
Conclusion
Well, I think that's all of it. If it isn't, I'll be editing this later, I guess. I hope that some of you found this tutorial informative, if a bit long winded and full of vocabulary that belongs in a museum or college classroom. I made this tutorial in an effort not only to help all of the scripters who may read it, but also in an attempt to help heal a horrible, horrible wound in this community's scripting habits. I'm sorry if any of you may have found this tutorial boring, offensive, or dumb, but that doesn't mean I don't think it wasn't worth posting. Any constructive criticism on the tutorial would be much appreciated. Thank you, and have a nice day.
