Comments (Scripting): Difference between revisions
>Camoy numeration isn't necessary |
>JulienDethurens No edit summary |
||
| Line 1: | Line 1: | ||
[[File:CommentExample.png|300px|thumb|right|An example of a comment in [[Studio]]. The comment is on the first line and is in green font.]]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: green; font-weight: bold;">green</span>. | |||
==Short Comments== | |||
A comment starts with a double hyphen (--) anywhere outside a string. These are short comments and they run until the end of the line. | |||
{{Example| | |||
Here is an example of a short comment: | |||
<code lua> | |||
-- This is a comment! | |||
</code> | |||
}} | |||
==Long Comments== | |||
== | Comments can also be defined using a long format enclosed by long brackets. We define an opening long bracket of level n as an opening square bracket followed by n equal signs followed by another opening square bracket. So, an opening long bracket of level 0 is written as [[, an opening long bracket of level 1 is written as [=[, and so on. A closing long bracket is defined similarly; for instance, a closing long bracket of level 4 is written as ]====]. A long comment starts with an opening long bracket of any level and ends at the first closing long bracket of the same level. Comments in this bracketed form can run for several lines and ignore any long brackets of any other level. They can contain anything except a closing bracket of the proper level. | ||
{{Example| | |||
Here is an example of a long comment: | |||
<code lua> | |||
--[===[ | |||
This is a long comment. | |||
It can contain hyphens, like this: -- | |||
It can also contain long brackets of another level than its own level, like this: [====[, or even [[ | |||
And they can be closing long brackets, like this: ]====] | |||
]===] | |||
</code> | |||
}} | |||
==Strategies for Useful Commenting== | |||
==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. | 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. | ||
| Line 61: | Line 48: | ||
==See Also== | ==See Also== | ||
*[http://www.lua.org/ | *[http://www.lua.org/manual/5.1/manual.html#2.1 Lua 5.1 Reference Manual: Lexical Conventions] | ||
[[Category:Scripting_Tutorials]] | [[Category:Scripting_Tutorials]] | ||
Revision as of 06:31, 27 January 2012
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.
Short Comments
A comment starts with a double hyphen (--) anywhere outside a string. These are short comments and they run until the end of the line.
Here is an example of a short comment:
-- This is a comment!
Long Comments
Comments can also be defined using a long format enclosed by long brackets. We define an opening long bracket of level n as an opening square bracket followed by n equal signs followed by another opening square bracket. So, an opening long bracket of level 0 is written as [[, an opening long bracket of level 1 is written as [=[, and so on. A closing long bracket is defined similarly; for instance, a closing long bracket of level 4 is written as ]====]. A long comment starts with an opening long bracket of any level and ends at the first closing long bracket of the same level. Comments in this bracketed form can run for several lines and ignore any long brackets of any other level. They can contain anything except a closing bracket of the proper level.
{{Example|
Here is an example of a long comment:
--[===[
This is a long comment.
It can contain hyphens, like this: --
It can also contain long brackets of another level than its own level, like this: [====[, or even [[
And they can be closing long brackets, like this: ]====]
]===]
}}
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.
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.
Precede Comments by a Blank Line
Doing this creates a distinct separation between your code and comments. Plus, it’s visually pleasing.
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.
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.
Comment While You Code
The chances of you commenting a finished project are slim, so do yourself a favor and comment your code immediately, so you can come back later and know what that piece of code was doing.
