Commenting

<< Programming in Lua | Lua | Variables >>

Commenting is essential when writing software. Sooner or later one will forget what he has wrote. Writing comments can help you to write the idea down.

Comments won't change the way your script is executed.

You can comment single lines in lua by prepending something with two dashes:

Example:

 var = 21 -- this is a comment

You can write longer comments by adding two brackets squared breaks at the front and end of your comment. Like this:

Example:

 var = 21 --[[ this is a comment
that goes over
multiple lines]]

Why and what needs comments?

A word on making comments...

It is a bad style not to comment code (I hardly comment my code...). But personally I prefer less commented code since the comments are often more helpfull if they only explain things that are really needed to be explained. If comments are everywhere, complex pieces of code are hard to spot.

Example

x,y,z = 1,2,3 -- set x = 1, y = 2, z=3
print((x^2+y^2+z^2)^0.5) -- print length of the vector

The first comment here is useless. If you know the programming language, you will know what the first line does. It is senseless to explain what you write - explain what you do and why you do it. The second comment is much more worthy: It explains a algorithm and what it does.

Another thing is, that you should name your variables and functions in a way that are self-explaining.

Example

function foo(a,b,c) return (a^2+b^2+c^2)^0.5 end
function distance(x,y,z) return (x^2+y^2+z^2)^0.5 end

Although both functions are doing the exactly same thing, the first one is less useful than the second. Whenever you use foo in your script files, one will stumble over these functions each time it is used if it is not clear what it means.