First and foremost before we get started please remember-- this is not the official style guide of Lua or Luau.
The purpose of following a style guide is to keep consistent and clean code. You may choose to follow or take inspiration or if you’re not here to learn about style practices, you may simply read this for enlightenment. This guide assumes you have a general understanding of Luau. This guide also goes into depth into why you should follow such practices. The goal of this style guide is to promote styles that respect the modified LSP of Lua 5.1 external Luau-like analysis that is also in regards to developer ergonomics. This guide values styles that promote readability and in a language that is being constantly optimized-- the era of focusing on performance over readability is slowly coming to an end.
This guide at the moment does not support static type checking.
Please feel free to share your opinions or correct me if I have worded or explained something weirdly. I will try to update the guide more when possible.
Comments should be kept minimum, provide comments only when needed.
What?
Comments are vital for documenting your code and the thought process behind it. I would agree that superfluous or unhelpful comments do hinder readability, but that’s not a reason to avoid them; you should instead strive to write meaningful comments that primarily address why something is being done, as opposed to what is being done.
I can see how the first sentence of their explanation is misleading because comments are definitely a vital part of your scripts. But I believe the author was trying to say that comments should only be used when they are absolutely necessary, or basically don’t use comments if they aren’t needed. I would say it is fine to have documentation and even comment headers for functions, but the author is trying to say that if the code is already obvious you don’t have to go in to depth about what each and every thing does.
That’s fair if so, but that section definitely needs rewording if that’s the case - it’s too vague about how exactly comments should be written, and where they should be applied, which is why I got the impression I did.
To begin with, readability is already a subjective matter however I can only share my opinions and thoughts with you. A comment may be used to amplify the importance of something that may otherwise seem inconsequential-- but this is how far it should really go. Personally having to write up comments is like an excuse for how unreadable your code is. I do agree with coming up with meaningful comments as long as these are very direct and compact comments that don’t clutter your code up. Authors, as mentioned in the guide, also agree on this matter. Although it may seem I have worded or not have addressed this clearly, thanks for commenting.
(I still don’t 100% agree, but your position is definitely a lot more reasonable than I first thought. I’ll leave my thoughts for another topic so as not to derail this one)
Although commenting needs to be kept minimal, during the workflow before the product would not be necessary. I usually employ a strategy of commenting while the product is in work and then throwing the comments together if necessary or erasing them entirely. This helps tracking your previous work’s end. Most comments I use aren’t intended for others and the final product’s comments are often rearranged properly or removed if not sustainable.
It looks very similar to the official Lua style guide by ROBLOX. I think that especially the CONSTANT and Class:_PrivateFunction() conventions are really neat. The main reason why I like this guide is that it does not look overcomplicated (too many comments and too much obsolete styling).
