To comment sections or not to comment sections?

I generally try to adhere to the Roblox style guide, my thinking being that if a large company uses it, then it must have merit. However, I have always disagreed on the “No section comments!” rule. I personally find them helpful to provide a visual barrier between related chunks of code. For instance, here’s an abbreviated version of something I just started writing:

-- some variable declarations

----------------------------------------
----| Object |--------------------------
----------------------------------------

local Effect = {}
Effect.__index = Effect

function Effect.new(effect, lights, form)
	return setmetatable({
		Effect = effect,
		Lights = lights,
		Form = form or {Name = "Flat"},
		Playing = false
	}, Effect)
	
end

----------------------------------------
----| Getters and Setters |-------------
----------------------------------------

function Effect:GetEffect()
	return self.Effect
end

-- more getters 

function Effect:SetEffect(effect)
	self.Effect = effect
end

-- more setters

----------------------------------------
----| Methods |-------------------------
----------------------------------------

function Effect:Start()
	if self.Playing then
		warn("MAC2000: This effect is already running.")
	end
end

function Effect:Stop()
	if self.Playing then
		warn("MAC2000: This effect is not running.")
	end
end

return Effect

Sectioning the code based on similar types of structures like “Getters and Setters” and “Methods” is restrictive, but I could also section it based on the purpose of the structures. e.g. a weapon module with a section for “Reload” and a section for “Shoot.” And when scripts start to get large, section comments become increasingly helpful. So why then does Roblox advise not using them?

1 Like

I’m not sure why, but it likely comes down to preference. Someone has to set a standard, otherwise code turn into a wild west of ideas. Even with lots of style guides, you can still usually tell who wrote a section of code. I know when I worked there we had a few discussions on style and it came down to what developers were familiar / comfortable and made sense at the time.

Now that I think about it, they probably added the no section comment rule as result of a code review when someone did it and someone else who doesn’t like it saw it. The decision probably would have then been influence by sections not being standard in the code base so it became a unity issue.

1 Like

In all honesty, like said above it comes down to personal preference. Comments aren’t game changing so I don’t see why it should matter whether you do or don’t use them. Depending on how you format comments, some could say makes the code LOOK messy, yet the look of it doesn’t matter aslong as you’re getting the output you intended. So to answer your question, there’s no real reason why roblox recommends not using them, it’s just down to your preference

I think the style guide is assuming that anything worthy of a section comment should be split off into a module script. Our codebases aren’t always so large as to demand such compartmentalization, so by all means, use comment sections if it improves your workflow.

I always use comment sections, they help me to outline my code. I always stick to the same general order: “Shortcuts” first (i.e. instances and services), then Modules, then Variables, then local functions (excluding once relating to a class), then constructors/terminators, then all other object-oriented functions, and then finally event handling.

I wouldn’t use comment sections to split up my scripts further, since they tend to be quite short. I also stick to 2 line comment sections at most, I have seen some code with obnoxiously large comment sections and it looks terrible.

Does the Roblox style guide demand zero documentation too? From reading the Roblox Chat script, I think that might actually be the case. That mess doesn’t really give me much confidence in a “roblox style guide.”

1 Like