All,
To add to Andre's comments about benefits of code commenting, /{ and }/ (or any
equivalent that uses open and close braces) allows the IDE editor's
brace-balancer to work, which in turn helps the user with finding endpoints of
commented-out code.
Commented-out code should be *syntactically* distinguishable from standard
comments (non-compilable text for humans) because, among other things, it
allows programs *other than the Swift compiler* that might parse or analyze the
Swift code to know how, for example, to typeset commented-out code which might
have a different typestyle from whatever is found (and possibly marked up) in
standard /* ... */ or // comments.
A program I've been working on, which converts one's code directly to
documentation using markup in /* ... */ and // comments only, recognizes
/*{...{
<code> /* with nested block commented text */
}...}*/
as a comment markup syntax to declare nested code comments, where the number of
one or more {...{s must match an eventual }...} (same number of braces) and be
different for each level. This makes it possible to catch mismatched nested
delimiters more easily, at the same time as dis-incentivizing more than, say,
two levels.
Delimiters /{ and }/ would work more succinctly, and a non-compiler parsing
program such as mine could still implement the multiple brace syntax, whether
it was part of the Swift language syntax or not.
I've also implemented (in my program) the recognition of
<code> //; <commented other code>
as a means of commenting one line of unused or related code, again as a means
of distinguishing text from code in a gloss-type comment (one that terminates
at the line's end), so as to treat this type of comment differently from the
usual // <comment text> in a final document.
- Doug McKenna
Mathemaesthetics, Inc.
Boulder, Colorado
----- Original Message -----
From: "Andre Ponzo" <[email protected]>
To: [email protected]
Cc: [email protected]
Sent: Saturday, August 27, 2016 1:03:11 PM
Subject: Re: [swift-evolution] [Idea] Distinguishing code comments from
text comments.
Good day, swift-evolution followers,
After reading Doug McKenna's email, I also see advantages in using specific
syntax to disable code instead of commenting it out.
To illustrate these ideas lets pick the more appropriate syntax (in my opinion)
proposed by Doug: /{ ... }
For example:
/{
print("Disabled code")
}
will produce the same result as:
if false {
print("Disabled code")
}
1) Advantages of disabled code ( /{ ... } ) instead of commented-out code (/*
... */):
1.1)
The disabled code will evolve in case of refactoring. Variable and function
names will be still valid the day the developer decides to re-enable the code.
Similarly, it prevents dead code inside comments:
let x = 0
...
/{x += 1} // will cause a compiler error if the first and last lines are
deleted.
print(x)
1.2)
Permits the use of dedicated syntax colouring in the IDE.
1.3)
Permits correct indentation of the commented code (taking surrounding enabled
code into account).
2) Advantages of /{ ... } instead of "if false { ... }":
2.1)
The IDE will not generate the warning "Will never be executed".
2.2)
It is more convenient.
For example suppose we have cond = true and a variable x, and that we prefer to
add 2 to x instead of 1:
original code: if cond {x += 1}
- "if false { ... }" syntax: if cond if false {x += 1} {x += 2}
// compiler error.
- "/{ ... }" syntax: if cond /{x += 1} {x += 2} // OK.
2.3)
Semantically:
"/*" initiates a text comment. The symbol * refers to text as it is used in
typography to mark footnotes.
"/{" initiates a code which is not executed. "/{" looks like "no {".
André Ponzo
DifferentApps.com
Geneva, Switzerland
_______________________________________________
swift-evolution mailing list
[email protected]
https://lists.swift.org/mailman/listinfo/swift-evolution
