[swift-evolution] [Idea] Distinguishing code comments from text comments.

[Doug McKenna]

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" <andre_ponzo at differentapps.com>
To: swift-evolution at swift.org
Cc: doug at mathemaesthetics.com
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