I like it overall… If you don’t mind though I’ll comment on a few things:
1. Write your code such that you don’t need comments.
Name things crystal clear and keep your logic (as) simple (as possible). With the sole exception of comments for function/API documentation, never write a comment explaining what a piece of code does — if you need that comment, your code isn’t clear enough. Comments are a brilliant tool for explaining why you’re doing something, though. Let your code explain the what and your comments explain the why.
(Yes, document your functions with comments!!! (I sometimes don’t lol))
(Also section header comments are fine, but subjective as to whether to use them)
2. Naming conventions
Over the more-than-half-a-century that people have been developing software, here is the total amount of universal naming conventions and standards that all software engineers have been able to agree on: 0.
Naming things is subjective. There are only three rules:
- Stay consistent.
- Stay consistent.
- Stay consistent.
For new projects, I use camelCase for local variables and basically anything that doesn’t leave the script. But for table members, exported fn names, etc. I use PascalCase to be consistent with the way the Roblox Engine names things. If i require a service or a module, the variable name for it is exactly the name of said service or module. Then, if I’m onboarded to a project that doesn’t do the same, I’m prepared to throw all of these conventions out the window to stay consistent with the project. Consistency is key — if you can’t do anything else, at least be consistent.
3. Type checking is a tool for you to use, not a god for you to serve
Paraphrasing the wise grugbrain.dev, 90% of the benefit of type checking is “I can type a ‘.’ and see in a little menu all the things I can do with this object.” Type correctness is cool and all, but Luau isn’t statically typed, and is built on a language that was never meant to be statically typed. As such, if you blindly decree that “All types shall be correct, thus sayeth the Lord,” you’re going to build all kinds of tables with metatables and functions and type unions as is possible in lua, all the while fighting the awkward type system in a futile effort to please some type checking god of your imagination — all the while never actually changing any of the functionality of your code with the type annotations you add.
I’m not saying that type checking is bad, I’m just saying that I prefer to use it for what it’s useful for, and nothing else. You will never catch me typing --!strict at the top of my editor (just as before, I am prepared to throw this convention out the window if it’s required to be consistent with a project).
An important note about --!native
While a script marked as native won’t permit you to pass in arguments of improper types, that’s not what native code gen is for. Native code generation takes your script, which would usually be interpreted, and causes it to be compiled to native machine code so it’ll run without the slowdowns of the interpreter. This is very cool, but has some drawbacks (which you can read about here) meaning you don’t want to enable this on every script in your game. So I do not recommend using --!native to handle type issues. Let the type checker handle type issues.