Lua Comment

This chapter would be easy I promise. Yet the skill you learn will be important: How to comment in Lua? If you are new in coding, commenting your code is an essential practice for any programmer. It is because good comment make your code more readable and maintainable, both for yourself and for others who may work with your code in the future. In Lua, just like any other programming languages, comments are pretty straightforward and easy to use. I will cover most of the common comment styles here.

Types of Comments in Lua

Single Line Comments

Single-line comments are used for brief notes or explanations. The syntax is simple, they begin with two hyphens --. Anything following the -- on that line will be ignored by the Lua interpreter. For example:

-- This is a single-line comment
print("Hello, World!")  -- This is also a single-line comment

In the above example, you can tell the only functioning script is “print(“Hello, World!”)”. Those wording after -- will be just for our own reading. So when you compile the Lua script, you should only see the result “Hello, World!”. All the comments will not be processed.

Multi Line Comments

Sometime, you may want to write more comments to explain what the block of codes doing. For longer explanations or block comments, Lua uses --[[ to open the comment and ]] to close it. Everything between these markers is treated as a comment. Let’s see below example:

--[[
This is a multi-line comment.
You can write as many lines as you want.
Just remember that all of them will be ignored by the Lua interpreter!
Good luck :)
]]
print("Hello, World!")

Again, only the print statement will be executed.

Nested Multi Line Comments

In some situation, you may want to create nested comments. Lua supports nested multi-line comments by using --[[ and ]] within another set of --[[ and ]]. This is particularly useful if you want to temporarily disable a block of code which already contains multi-line comments. The below example is for your demonstration.

--[=[
This is a nested multi-line comment.
--[[
This inner comment is also ignored.
]]
The outer comment ends here.
]=]
print("Hello, World!")

Best Practices for Commenting

From my personal experience, many software developers look down on the importance of good comments in the program. If you can write Clear and Concise comments, you can save the world. Comments should be easy to understand. Avoid writing overly complex explanations.

Also, instead of stating what the code does, explain why it does it. The code itself should be clear enough to explain what it does. Moreover, try to keep comments Up-to-Date. Since outdated comments can be more confusing than helpful. Make sure your comments reflect any changes you make to the code. Last but not least, try to use comments to break down section. Especially for longer scripts, use comments to break down sections by section. This makes it easier to navigate.

Example of Good Commenting Practice:

-- Function to add two numbers
-- This function takes two arguments, a and b, and returns their sum.
-- Add a and b

function add(a, b)
    return a + b  -- Add a and b
end

-- Call the add function with 5 and 3, and print the result

print(add(5, 3))  

By following these practices, you can make your Lua code more readable and maintainable.