Hey there! I’m MrAsync. I’ve been programming with Lua for almost 4 years. I’ve been improving constantly and have learned a lot. However, I’m at a point where I would like to improve my code organization, efficiency and readability.
What am I looking for?
To put it simply, I would like some tips for the following from experienced programmers
Commenting styles
Efficiency
Code organization
General tips
Here’s some examples of my current code as a reference. Am I commenting too much? Are my functions efficient? How is my inner-script organization?
First off, your editor colors are on point. I’m gonna need to see the sauce on that chief
I like your spacing.
I think you have way too many comments, which can get confusing fast. I think the “Asyncronously flip vehicle” comment is the only one that is arguably worth keeping here since it summarizes a block of code; every other comment here is not really helpful to pointing out anything that is not already very obvious just by reading the code.
Your variables are well named.
Mostly a personal preference, I think you could benefit from either using guard clauses, or grouping your conditional statements up more.
if (gameProcessed) or (not vehicle) or (inputObject.KeyCode == Enum.KeyCode.F) then return end
or, spaced out differently (idk if this is considered messy or not)
if (gameProcessed)
or (not vehicle)
or (inputObject.KeyCode == Enum.KeyCode.F)
then return end
or
if (not gameProcessed) and vehicle and inputObject.KeyCode == Enum.KeyCode.F then
--code
end
I think your code is pretty much fine except for the over-commenting.
Comments
You are commenting a bit too much in my opinion (mostly regarding to the part where you comment about creating a new maid and a new bodygyro). I usually find comments to best fit areas where it’s hard to tell what is happening. They’re also handy when put above blocks/conditions to explain what the block/condition does so it’s easy to return to an area if you’re going to add to it.
Efficiency
When it comes to your VehicleController class, it doesn’t seem like you’re fully utilizing the features of OOP. The class itself could hold a reference to the player’s current vehicle using getter and setter functions rather than depending on an external value. ContextActionService would be better to use than UserInputService in this case since you can bind and unbind the actions depending on if a user is in a vehicle or not (which would remove having to listen for client input while not in a vehicle). It seems like canFlip isn’t a member of the VehicleController class meaning that your code will only allow one vehicle to flip at a time (since all the VehicleControllers are using the same variable to see if they’re able to flip).
Organization
For the sake of readability it’s nice to have all your variables together (this applies to the top of blocks) it makes it easier to see what everything is assigned to. You do a pretty good job of this as it is.
Everyone is going to have different opinions. The important part is why you stick to a style: Sticking to a style helps you write clean code that is easier to debug and maintain later. It also helps reduce unnecessary bugs in certain ways.
The only thing I would change from your code personally is reducing comments. Comments are used to either document usage or to explain code that might not be easy to understand just from looking at it. And if you follow that pattern, then more comments usually correlates to messier or unclear code.
I also recommend sticking somewhat close to the common styling practices per language. Therefore, your style might actually change between writing Lua and Python (e.g. people usually use “camelCase” in Lua, but “snake_case” in Python). This will help maintainability when other people need to touch your code.
For commenting, I find it better to focus more on broad explanations of what a block of code does and how it’s doing it, as well as good documentation for variables that aren’t immediately obvious by looking at their name.
It seems like you’re mostly focusing on just describing what each line does when that line is obvious to anyone with a non-negligible degree of knowledge regarding scripting.
I think about it this way when I comment: if you were to abandon all your code for a year then come back, what would help the most?
I’d know what the Instance.new is doing, and what it means when you’re adding it to maid. But what I’d want to know is knowing what each function does, what it returns, and what it takes as arguments, and potentially what it’s used for and a brief overview of how it accomplishes what it does.
Like the “bind to value changed” comment; I know that just by looking at that code as it’s standard readable Rbx Lua. What I’d want to know is why this is being done, and what for.
…I probably overcomment myself, but best to keep in mind it’s still much better to focus on explaining what/how/why for things that wouldn’t be obvious to someone who knows Rbx Lua but not your project’s codebase. And this applies regardless of quantity of comments.
Two miscelleaneous code tips, though: would it not be more efficient to use self.Player:WaitForChild(“playerVehicle”) instead of the repeat wait() loop? You could also use :GetPropertyChangedSignal(“Value”):Wait() on playerVehicle.Value instead of doing the wait loop if you’re confident that if the value is changed it won’t be to nil.
And while you may know what you’re doing, it’s recommended generally not to use the second argument of Instance.new() for parenting things, but rather parent them manually after you’re done modifying them due to the load it introduces when put into workspace.
