Comments

Code - on its own - is not always capable of explaining its nuances and reasonings; sometimes, there's too much complexity/intricacy for self-documentation to be able to convey.

In another case, code may be too dense with unrelated sections seemingly blending together with no divider to suggest otherwise; resulting in any potential self-documentation being lost.

Comments are fantastic for both of these scenarios, serving as a tool to aid Documentation and Organization. However, there is a point where commenting too much can be a detriment to readability.

Acceptable Cases

There are only a few cases where Commenting should be utilized:

• With Code that relies on context indeterminable through the Code itself

const RequestPositionSync = () => {
	const startedAt = performance.now()
	return (
		/*
			IsLocal determines whether or not we are playing on the current device
			OR if we are playing on a different device (device switching).

			For local playback, we can use the Clients C++ Transport to get the current position.
			Otherwise, we have to request for a timestamp resync from the Active Device to get the
            current position.
		*/
		SpotifyPlatform.PlaybackAPI._isLocal
		? ...
        : ...

^{Example from the "Spices" Package used in Beautiful Lyrics (a Spotify Extension)}

• To separate Unrelated Sections of Code or Large Sections of Differing Functionality

-- Roblox Services
local Shared = game:GetService("ReplicatedStorage")
...

-- Game Services
...

-- Packages
...

-- Constructor
function CreateInterface(...)
    ...
    -- Handle updating our status
    ...
    -- Handle showing actions based on context
    ...
...

^{Example from an Interface module used in Car Crushers 2 (a Roblox game)}

• To indicate future work/changes

-- TODO: Needs to check tag precense to be accurate
-- function RenderTools:GetVisibleValue(...)

^{Example from the RenderTools module used in Car Crushers 2 (a Roblox game)}

Excessiveness

Commenting SHOULD NEVER be used to restate what the code already communicates. An example of this can be seen here:

// Load our song details AND lyrics
HasIsLikedLoaded = false
LoadSongDetails()
LoadSongLyrics()

// Fire our events
SongChangedSignal.Fire()

^{Ironically, also an example from the "Spices" Package used in Beautiful Lyrics (a Spotify Extension)}

This is excessive, it provides no additional detail that the code does not provide to the reader already. This can be simply written as:

HasIsLikedLoaded = false
LoadSongDetails()
LoadSongLyrics()
SongChangedSignal.Fire()

There is also a common pattern where sectional comments are extravagantly done, for example:

/*=============================================================================
                                  Section Name
*=============================================================================*/

This is overly excessive. These types of sectional comments take up significantly more vertical/horizontal space than they should and creates unnecessary friction in cooperative workspaces; an autogenerated snippet you may have or workflow you are willing to put up with is not something other developers may possess. Comments should be as simple and utilitarian (yet refined) as possible; and this is the complete opposite.

Formatting

Comments are ONLY allowed in three configurations:

/* Multiline Above
    ...
*/
const X = ...

// Single-line Above
const Y = {
    Property: ..., // Single-line Side
}

There should NEVER be any whitespace between the comment and following code, the two lines should always be next to each other.

Additionally, there are the guidelines for each type of configuration:

• Multiline
• • Inner-text MUST be at minimum indented a singular tab relative to the starting tab-depth of the comment.
  • If any line within the comment exceeds the vertical ruler it must be wrapped to the next line.
• Single-line Above
• • There MUST be a singular space between the comment token ("//", "--", etc.) and the following text.
  • IF the comment exceeds the vertical ruler it MUST be turned into a Multiline comment.
• Single-line Side
• • There MUST be a singular space between the comment token ("//", "--", etc.) and the following text.
  • IF the comment exceeds the vertical ruler it MUST be turned into a Single-line Above comment.

Each configuration falls back onto the one prior as to ensure we have comments that are structurally easy to read and predictable in nature.