Hello everyone, Boggarak here!
I’m currently a Software Engineering student, and there are some good pieces of programming advice I could give you that could not only help you with coding your games on Roblox, but also coding elsewhere. This will be a multi-part series that will cover coding advice that you ideally should start using when coding in Roblox, as it will definitely help you when working on your projects and help you become a better programmer.
The first topic I will cover are about comments. If you have programmed on Roblox before, you probably have known or at least seen what a comment is. For those who still don’t know, comments are lines in code that does absolutely nothing, and usually contain text. In Lua, comments are indicated using dashes -- ... and square brackets with dashes --[[ ... --]].
While they can be used for debugging (like disabling certain pieces of code in a given script), their real purpose is for readability, or the ease of understanding what a section of code does. Some programmers add a lot of comments, while some don’t even add any comments. However, the most important thing when writing a comment is when you should write a comment, and when you can get away with not writing one.
I will give you a list of instances of when you should write a comment (and instances where comments are not really preferable). For all of these instances, the key idea is that, if a given piece of code is easily readable, then the programmer should know in seconds what a given section of codes does, and doesn’t require mental gymnastics or a lot of deciphering to understand it.
With that said, here is a list of instances to consider when write a comment:
Writing Documentation Comments
Documentation comments are multi-lined comments that are used to allow other people to understand how to use the code you give them, whether it is a function, a class, or even the entire script or file. The purpose is that people can use your code without caring about how it is implemented (or coded), but instead if it does what they want it to do.
For example, let’s say we made a Lua module that contains functions that one can use to ease the process of creating a minigame-type Roblox game (like Ripull Minigames). In that case, I would have a documentation comment for the entire module, describing briefly on:
- its purpose (i.e. make it easier to create a minigame-type game)
- who made it (i.e. you and the other people who have worked on it)
- the version of the module
- the date of when the module was first made (depends on the situation)
Then, I would write a documentation comment for each of the (public) functions I want the people using this module to use, since they will need to do so to create their game. For each function, the documentation comment will include:
- A brief description of what the function does
- What to put into the function, if applicable
- What is the output of the function, including what kind of output (i.e. is it a piece of text, a number, etc.) and what the output represents. again, if it’s applicable.
Then that would be it. Don’t write documentation comments within functions, as the person using the module doesn’t care about how the function actually works, but rather, as I said before, if it does what they want it to do.
How to write a documentation comment will vary depending on the programming language you are using, and Lua doesn’t really have a universal style of writing a documentation comment. However, the things I have listed should be sufficient for a decent (or even good) documentation comment.
Let’s do an example of writing a documentation comment. Using the same example as before, let’s say we have the following function in the code
function minigameModule.teleportPlayer(player, toLocation)
-- Code to teleport player to location (ignore this, as it isn't really important)
end
To write a documentation comment, we will make a multi-lined comment above the function (as it will be the first thing the person will see, since we read code from top to bottom). In this, we will include everything that I mentioned earlier about documentation comments for functions. After which, the code now looks like this:
--[[
Teleports a given player to a given location
@param player Player the player being teleported
@param toLocation Vector3 the location the player will be teleported to
--]]
function minigameModule.teleportPlayer(player, toLocation)
-- Code to teleport player to location (ignore this, as it isn't really important)
end
Note that the function doesn’t return an output, since it doesn’t really need to. If you plan to have a function that does return something, describe what that is in the comment, preferably using the statement like “returns …”.
It is important to mention that you don’t need to write documentation comments for the most part, and when you should depends on several factors that relate to what you are working on. You can get away with not writing them as long as it is clear to other people how to use the code based on just code itself, which leads to my next point:
Best Comments are the names of Variables, Functions, Classes, etc.
I really need to emphasize that you don’t always need to write a comment, as there are alternatives that do a better job in certain instances. The point here is to give you other tools to help make your code more readable, and it is a bad idea to only use one tool when there are others that do just as well (or even better). As a wise person once said, “If you only use a hammer, everything will look like a nail”.
With this said, I will describe ways where this tactic is the most useful. One of these instances is when you have a rather messy if statement like this:
if (dist > 0 and dist <= PieceSize*math.sqrt(2)) then
-- Do something
end
Tell me, what is the if statement checking? I can tell that some of you might have taken like 10~15 seconds to figure out what is being checked here, more or less, or some of you still don’t even know what is being checked.
Okay, what about this?
isNearby = (dist > 0 and dist <= PieceSize*math.sqrt(2))
if (isNearby) then
-- Do something
end
Most of you should have known what the statement is checking almost instantly or at least less time than the other if statement. Notice that I didn’t add any comments describing what the if conditional does (although I could if I wanted to), but yet you could clearly get what is being done here, or at least a very good idea.
The kind of variable I used here is called an extract variable, and they are primarily used for making conditionals easier to understand. All extract variables are boolean (i.e. either true or false), since that is the only kind of variable that is allowed to function as a conditional.
However, tactic would be useless if the variable name was like a or conditional since they don’t provide information that describes what the variable means or even is used for. This is why you should have good (i.e. descriptive) names for your variables, functions, and classes, since they can go a very long way in making your code easier to understand.
Note that when I mean descriptive, I don’t mean long. What I mean is that one can clearly get what the variable, function, etc. represents just from its name. As long as it clear in context, a short, but descriptive name should suffice.
There are also extract functions (or extract methods for Object-Oriented Programming), which are used to make a complex function (that does a lot of stuff) easier to understand, but I’ll save that for next time.
I want to mention that you don’t always need to do this, and in most cases its preferable to not do this, especially where performance or memory are crucial (extract variables and functions can waste valuable memory), which, in that case, a comment would be better. However, try to make sure that you choose good names for your variables, functions, and classes so that it is easier to get what is being done. Analyze what kind of requirements you need your program to follow and apply any techniques that are appropriate
Comments are a Last Resort
Comments can very easily waste memory (and the time of the programmer, if they see more comments than code), which is especially bad since they don’t really do anything, so it is important to emphasize that, again, you don’t need to comment if you if it is not really needed.
Instead, see if the code can easily be understood by itself. If not, instead of immediately writing a comment, ask yourself* why* it is not easily understood. Are the names for variables too vague or even meaningless? Is the logic too complex?
If you have meaningless names or names that are too vague (see previous section), change them so that people can easily get what the variable or function represents. See if the name makes sense in the context of the code. If the variable name is still too vague or is way too long, then a comment that adds more of the important details will do the trick, as long as the variable name you chose is good and relates nicely to the context of the code (see the previous section).
If you have logic that is too complex, see if you can simplify it. This can require you to learn about boolean algebra, especially for complex conditionals, which I will cover in a later section, but there are still meaningful ways of reducing complexity of a piece of code. If you can’t simplify it any further and the code is still a mess, a comment describing the function and purpose of the algorithm would be fine.
Ideally, you want to minimize the use of comments in your code, and only include comments that have a very good reason of being there. Usually, if you do need to add a comment, a comment that describes why that piece of code exists or does something in a particular way is usually the best comment to write. Never write comments that simply describes how the code works, as the programmer can get that information from just the code itself. There are exceptions (see section 1), but for the most part, you shouldn’t even bother writing a comment that describes how the code works, as, if the code is well written, then any programmer can get that information from just the code itself.
This is all I have for now. However, if you have any goo
d suggestions on what I can add here, then please comment below (pun intended). I’ll update this if I have more ideas of what to add here (or to include the link to the part of this series).
Otherwise, see you next time when I cover the DRY principle and what it really means when coding.
Resources (Recommended):
Next Post: Good Coding Practices II - The DRY Principle
- Source Making - Comments
- You’re commenting your code too much (and other controversial thoughts on documentation) (Thanks Vizualizememe for the article).