I like how Lua handles the problem, with multi-level open and close comment strings (and string strings). From Programming in Lua [1]:
> A comment starts anywhere with a double hyphen (--) and runs until the end of the line. Lua also offers block comments, which start with --[[ and run until the corresponding ]]. A common trick, when we want to comment out a piece of code, is to write the following:
--[[
print(10) -- no action (comment)
--]]
>
Now, if we add a single hyphen to the first line, the code is in again: ---[[
print(10) --> 10
--]]
>
In the first example, the -- in the last line is still inside the block comment. In the second example, the sequence ---[[ does not start a block comment; so, the print is outside comments. In this case, the last line becomes an independent comment, as it starts with --.Furthermore, the pairs of so-called long brackets ([[ and ]], which match the syntax used to declare multi-line string literals) prefixed with hyphens can be converted to 'level-n' long brackets by inserting an arbitrary number of '=' signs between them:
local commentDescribingString =
[===[Lua allows for multiple comment syntaxes.
You can use two hyphens: '--' for single-line comments.
Opening 'long brackets' with these hyphens (--[[) start block comments.
Long brackets can contain '=' signs to form different bracket pairs.
Closing long brackets must match the number of '=' signs, and do not
require the hyphens (but they look better and are more convenient)
These would be comments if they weren't in a string literal:
--[[ Level 0
--[=[ Level 1
--[==[ Level 2
print("this is really thoroughly commented out.") -- It is!
--]==] -- Closed level 2
--]=] -- Closed level 1
]] -- Closed level 0 without the hyphens
I had to use level-3 long brackets to declare this string.
]===]
print(commentDescribingString) -- Prints above paragraph
Single-line comments go to the end of the line, of course, no matter how many hyphens there are. Single-line strings can be declared with any number of single- or double-quotes:
local singleLineString = """This string with 'single', ''double single'', ""double"", or ""double double"" quoted words might be hard to write in other languages!"""
Of course, there's also 'if (false) then
(block of code) end' as in every language. The code still goes through the parser, so it takes compilation time if not execution time, and you can have scope conflicts, but that's OK IMO. Surrounding it in an 'if (false)' block is one quick step away from changing 'false' to 'true' to re-enable it, or changing 'false' to a variable to make it optional, which is nice.