This is a tutorial to cover the commenting features in RGSS. It contains some personal views on things, but it's basically a global tutorial.
Note that this tutorial does not cover the reading of comments in events or event comments at all.
Purpose of Commenting
While in most professional programs commenting is something very important, it isn't as essential in RMXP. Commenting is supposed to help other programmers understand your code, and since you work alone on a script most of the time, you don't need to guide other people through your work. On the other hand, if you submit a script, it might come in handy, as people who download it might want to change some things here and there to customize it. Of course, with larger scripts, it might make your life easier if you find a comment here and there on what a variable contains, connections of methods, this kind of stuff. It's basically for you to decide.
Another use for comments is commenting out script pieces. I'll explain this method further down.
Basic Knowledge
Commenting besically defines lines that won't be read by the RGSS Interpreter, and therefore won't affect your game. Commented text in the Script Editor is written green, which makes it easily recognizeable. You can comment every line of code, regardless of the content.
Comments aren't just ignored by the Interpreter, they're not read at all. That means, they won't affect your performance in any way, even if you'd have 10.000 lines of comments, as they're practically not there.
What to comment
You could comment every single line in a script to know what's going on there, what'd decrease the overview heavily. You could also totally leave out comments out of your script, which might be bad, too, because you miss a certain thing you might want to be remembered of. Therefore, you need to carefully choose between lines to comment and lines you can safely leave by theirselves. The necessary lines differ from script to script, so it's basically up for you to decide. Keep in mind that with further scripting experience, you'll get a feeling for what you need to comment and what not.
Line Commenting
If you decide to comment your script, you should know the two methods of doing this: Line and block commenting. You can comment every line by writing a '#' as the first character in the line.
Block Commenting
To comment whole blocks of text (most often used to write an introduction text or script instructions), use '=begin' and '=end' around the block, each in a line without any other content. Note that you can't use block comments in the middle of a script, just at the very beginning.
Commenting Out Code
You can also comment out lines of code that shouldn't be used temporarily, for example to debug your game or test something out. Of course, you need to take care about what you comment out, as it might reference to another part of the script, like conditional branches...
Comment Markers
You can also use comments as markers between method definitions, as it's done in the default scripts. It drastically increases the readability of your script, both for others and you, so it's a thing you should care about. The following example spoiler holds the same script without and with comment markers for you to see the difference.
Indentation doesn't serves the purpose alone, as you can see. This becomes even more obvious with bigger scripts. Take a look at DubeAlex' AMS, for example, which misses these markers completely - it's almost unreadable without in-depth knowledge of what the script does. Note that this doesn't matter at all if you just want to use it, as it works perfectly.
Note that this tutorial does not cover the reading of comments in events or event comments at all.
Purpose of Commenting
While in most professional programs commenting is something very important, it isn't as essential in RMXP. Commenting is supposed to help other programmers understand your code, and since you work alone on a script most of the time, you don't need to guide other people through your work. On the other hand, if you submit a script, it might come in handy, as people who download it might want to change some things here and there to customize it. Of course, with larger scripts, it might make your life easier if you find a comment here and there on what a variable contains, connections of methods, this kind of stuff. It's basically for you to decide.
Another use for comments is commenting out script pieces. I'll explain this method further down.
Basic Knowledge
Commenting besically defines lines that won't be read by the RGSS Interpreter, and therefore won't affect your game. Commented text in the Script Editor is written green, which makes it easily recognizeable. You can comment every line of code, regardless of the content.
Comments aren't just ignored by the Interpreter, they're not read at all. That means, they won't affect your performance in any way, even if you'd have 10.000 lines of comments, as they're practically not there.
What to comment
You could comment every single line in a script to know what's going on there, what'd decrease the overview heavily. You could also totally leave out comments out of your script, which might be bad, too, because you miss a certain thing you might want to be remembered of. Therefore, you need to carefully choose between lines to comment and lines you can safely leave by theirselves. The necessary lines differ from script to script, so it's basically up for you to decide. Keep in mind that with further scripting experience, you'll get a feeling for what you need to comment and what not.
Line Commenting
If you decide to comment your script, you should know the two methods of doing this: Line and block commenting. You can comment every line by writing a '#' as the first character in the line.
Code:
[COLOR=SeaGreen]#Hello World.[/COLOR]
Code:
[COLOR=SeaGreen]# This is a comment.[/COLOR]
Code:
@variable += 1 [COLOR=SeaGreen]# Increases @variable (integer) by 1[/COLOR]
Code:
[COLOR=SeaGreen]#These are single comment lines.
#It serves the same purpose as block commenting, it's just a different kind of commenting.
#Use this method to comment out large chunks of code in the middle of a script where block commenting won't work.[/COLOR]Block Commenting
To comment whole blocks of text (most often used to write an introduction text or script instructions), use '=begin' and '=end' around the block, each in a line without any other content. Note that you can't use block comments in the middle of a script, just at the very beginning.
Code:
[COLOR=SeaGreen]=begin
This is a block of comments.
It might be used to write the description of a script or instructions on how to use it.
You might also store informations about the script, like used variables, in there for personal reference.
=end[/COLOR]Commenting Out Code
You can also comment out lines of code that shouldn't be used temporarily, for example to debug your game or test something out. Of course, you need to take care about what you comment out, as it might reference to another part of the script, like conditional branches...
Code:
[COLOR=SeaGreen]#@variable +=1[/COLOR]
Code:
[COLOR=SeaGreen]#@variable +=1 # Increases @variable (integer) by 1[/COLOR]
Code:
[COLOR=SeaGreen]#if @variable > 0[/COLOR]
p 'Hello World'
[COLOR=SeaGreen]#end[/COLOR]Comment Markers
You can also use comments as markers between method definitions, as it's done in the default scripts. It drastically increases the readability of your script, both for others and you, so it's a thing you should care about. The following example spoiler holds the same script without and with comment markers for you to see the difference.
Code:
class Window_Gold < Window_Base
def initialize
super(0, 0, 160, 64)
self.contents = Bitmap.new(width - 32, height - 32)
refresh
end
def refresh
self.contents.clear
cx = contents.text_size($data_system.words.gold).width
self.contents.font.color = normal_color
self.contents.draw_text(4, 0, 120-cx-2, 32, $game_party.gold.to_s, 2)
self.contents.font.color = system_color
self.contents.draw_text(124-cx, 0, cx, 32, $data_system.words.gold, 2)
end
end
Code:
class Window_Gold < Window_Base
[COLOR=SeaGreen]#--------------------------------------------------------------------------[/COLOR]
def initialize
super(0, 0, 160, 64)
self.contents = Bitmap.new(width - 32, height - 32)
refresh
end
[COLOR=SeaGreen]#--------------------------------------------------------------------------[/COLOR]
def refresh
self.contents.clear
cx = contents.text_size($data_system.words.gold).width
self.contents.font.color = normal_color
self.contents.draw_text(4, 0, 120-cx-2, 32, $game_party.gold.to_s, 2)
self.contents.font.color = system_color
self.contents.draw_text(124-cx, 0, cx, 32, $data_system.words.gold, 2)
end
[COLOR=SeaGreen]#--------------------------------------------------------------------------[/COLOR]
endIndentation doesn't serves the purpose alone, as you can see. This becomes even more obvious with bigger scripts. Take a look at DubeAlex' AMS, for example, which misses these markers completely - it's almost unreadable without in-depth knowledge of what the script does. Note that this doesn't matter at all if you just want to use it, as it works perfectly.