Comments (Scripting): Difference between revisions
>Quenty Added a 'See Also' |
>Ozzypig No edit summary |
||
| Line 1: | Line 1: | ||
==Comments== | ==Comments== | ||
Comments are | [[File:CommentExample.png|300px|thumb|right|An example of a comment in [[Studio]].]]A comment in Lua is text that is completely ignored by the parser. Comments are annotations by the writer of a program to explain what the intent of the program is. Comments in ROBLOX Studio's editor are shown in <span style="color: #008000; font-weight: bold;">green</span>. | ||
===Single-line Comments=== | ===Single-line Comments=== | ||
| Line 11: | Line 10: | ||
-- This is an example of a comment | -- This is an example of a comment | ||
</pre>}} | </pre>}} | ||
===Block Comments=== | ===Block Comments=== | ||
| Line 24: | Line 21: | ||
]] | ]] | ||
</pre>}} | </pre>}} | ||
Notice how this comment is on more than one line. In the first example, it is limited to one line. | |||
===Leveled Comments=== | ===Leveled Comments=== | ||
| Line 31: | Line 30: | ||
{{Example|<pre> | {{Example|<pre> | ||
--[=[ | --[=[ | ||
This is a level 1 comment. | This is a level 1 comment. | ||
]=] | ]=] | ||
</pre> | </pre> | ||
| Line 38: | Line 37: | ||
<pre> | <pre> | ||
--[==[ | --[==[ | ||
This is a level 2 comment. | This is a level 2 comment. | ||
]==] | ]==] | ||
</pre>}} | </pre>}} | ||
==Strategies for Useful Commenting== <!-- http://particletree.com/features/successful-strategies-for-commenting-code/ --> | |||
Writing useful commentary is almost as hard as writing the code itself. It is all too easy to write whatever the code does, but not why it does so or the super-objective of the code. | |||
===1. Comment and Code in Paragraphs=== | |||
Write your code and comments in paragraph form. Break each piece of code into sequences that achieve a single task with comments in-between. | |||
===2. Precede Comments by a Blank Line=== | |||
Doing this creates a distinct separation between your code and comments. Plus, it’s visually pleasing. | |||
===3. Don't Insult Anyone's Intelligence === | |||
All commenting is not productive commenting. Too many comments can make your code less meaningful and therefore less readable. Tell us '''why''', not '''how'''. | |||
===4. Be Consistent=== | |||
There are many beliefs on the proper way to comment code. Some feel comments should be so detailed that a non programmer could follow the logic, while others believe you use comments for support. What matters most is that you are consistent in your commenting style. This helps your reader know what to expect when going through several different projects. | |||
===5. Comment While You Code=== | |||
The chances of you commenting a finished project are slim, so do yourself a favor and comment your code immediately. | |||
==See Also== | ==See Also== | ||
Revision as of 21:02, 26 December 2011
Comments
A comment in Lua is text that is completely ignored by the parser. Comments are annotations by the writer of a program to explain what the intent of the program is. Comments in ROBLOX Studio's editor are shown in green.
Single-line Comments
A comment starts anywhere with a double hyphen (--) and runs until the end of the line:
-- This is an example of a comment
Block Comments
Lua also offers block comments, which start with the first double brackets and run until the corresponding double brackets:
--[[ This is an example of a block comment. ]]
Notice how this comment is on more than one line. In the first example, it is limited to one line.
Leveled Comments
Leveled comments are comments that have different levels of toleration for lower-leveled comments, such as the above block comment.
--[=[ This is a level 1 comment. ]=]
Below is a level 2 comment, there is no limit to what level a comment is on. But a level 1 comment cannot hold a level 2 or higher, and so forth...
--[==[ This is a level 2 comment. ]==]
Strategies for Useful Commenting
Writing useful commentary is almost as hard as writing the code itself. It is all too easy to write whatever the code does, but not why it does so or the super-objective of the code.
1. Comment and Code in Paragraphs
Write your code and comments in paragraph form. Break each piece of code into sequences that achieve a single task with comments in-between.
2. Precede Comments by a Blank Line
Doing this creates a distinct separation between your code and comments. Plus, it’s visually pleasing.
3. Don't Insult Anyone's Intelligence
All commenting is not productive commenting. Too many comments can make your code less meaningful and therefore less readable. Tell us why, not how.
4. Be Consistent
There are many beliefs on the proper way to comment code. Some feel comments should be so detailed that a non programmer could follow the logic, while others believe you use comments for support. What matters most is that you are consistent in your commenting style. This helps your reader know what to expect when going through several different projects.
5. Comment While You Code
The chances of you commenting a finished project are slim, so do yourself a favor and comment your code immediately.
