[Idea] Distinguishing code comments from text comments.


(Andre Ponzo) #1

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


(Doug McKenna) #2

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@differentapps.com>
To: swift-evolution@swift.org
Cc: doug@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


(Magnus Ahltorp) #3

What are the advantages of this compared to conditional compilation (#if)?

/Magnus

···

27 Aug. 2016 21:03 Andre Ponzo via swift-evolution <swift-evolution@swift.org> wrote:

1) Advantages of disabled code ( /{ ... } ) instead of commented-out code (/* ... */):

2) Advantages of /{ ... } instead of "if false { ... }":


(Tino) #4

Just was about to propose this (existing) alternative.
I've already used it to store complicated breakpoint-actions in source, and was pleased that goodies like autocompletion work for inactive code (sometimes… as it does with normal code :wink:

Tino

···

Am 29.08.2016 um 20:20 schrieb Magnus Ahltorp via swift-evolution <swift-evolution@swift.org>:

What are the advantages of this compared to conditional compilation (#if)?


(Andre Ponzo) #5

The advantage is that you do not need to define a conditional flag for the #if.
It is also more concise.

Code disabling (with /{...}/) is a tool useful when developing algorithm, and disabled code should not be aimed to remain definitively in a Swift file.

Andre Ponzo

···

Le 29 août 2016 à 20:20, Magnus Ahltorp <map@kth.se> a écrit :

27 Aug. 2016 21:03 Andre Ponzo via swift-evolution <swift-evolution@swift.org> wrote:

1) Advantages of disabled code ( /{ ... } ) instead of commented-out code (/* ... */):

2) Advantages of /{ ... } instead of "if false { ... }":

What are the advantages of this compared to conditional compilation (#if)?

/Magnus


(Kenny Leung) #6

+1 from me.

-Kenny

···

On Aug 29, 2016, at 1:16 PM, DifferentApps info via swift-evolution <swift-evolution@swift.org> wrote:

The advantage is that you do not need to define a conditional flag for the #if.
It is also more concise.

Code disabling (with /{...}/) is a tool useful when developing algorithm, and disabled code should not be aimed to remain definitively in a Swift file.

Andre Ponzo

Le 29 août 2016 à 20:20, Magnus Ahltorp <map@kth.se> a écrit :

27 Aug. 2016 21:03 Andre Ponzo via swift-evolution <swift-evolution@swift.org> wrote:

1) Advantages of disabled code ( /{ ... } ) instead of commented-out code (/* ... */):

2) Advantages of /{ ... } instead of "if false { ... }":

What are the advantages of this compared to conditional compilation (#if)?

/Magnus

_______________________________________________
swift-evolution mailing list
swift-evolution@swift.org
https://lists.swift.org/mailman/listinfo/swift-evolution


(Jaden Geller) #7

You don't have to.

#if false {
    // disabled code here
}

···

On Aug 29, 2016, at 1:16 PM, DifferentApps info via swift-evolution <swift-evolution@swift.org> wrote:

The advantage is that you do not need to define a conditional flag for the #if.
It is also more concise.

Code disabling (with /{...}/) is a tool useful when developing algorithm, and disabled code should not be aimed to remain definitively in a Swift file.

Andre Ponzo

Le 29 août 2016 à 20:20, Magnus Ahltorp <map@kth.se> a écrit :

27 Aug. 2016 21:03 Andre Ponzo via swift-evolution <swift-evolution@swift.org> wrote:

1) Advantages of disabled code ( /{ ... } ) instead of commented-out code (/* ... */):

2) Advantages of /{ ... } instead of "if false { ... }":

What are the advantages of this compared to conditional compilation (#if)?

/Magnus

_______________________________________________
swift-evolution mailing list
swift-evolution@swift.org
https://lists.swift.org/mailman/listinfo/swift-evolution


(Magnus Ahltorp) #8

The advantage is that you do not need to define a conditional flag for the #if.

The good news is, you don't.

#if false
  print("Disabled code")
#endif

which is a time-tested way of writing C code (using #if 0).

From the Swift changelog, where they even call it an idiom of C:

2014-04-30
[…]
* You can now use the `true` and `false` constants in build configurations,
  allowing you to emulate the C idioms of `#if 0` (but spelled `#if false`).

One pattern I use all the time, both in C and in Swift, is this:

#if false
<experimental code>
#else
<old code>
#endif

which makes it possible to switch between the implementations quickly, something you cannot do with the proposed syntax.

Code disabling (with /{...}/) is a tool useful when developing algorithm, and disabled code should not be aimed to remain definitively in a Swift file.

Which is in no way dependent on if you use the proposed syntax, traditional comments, or conditional compilation.

/Magnus

···

29 Aug. 2016 22:16 DifferentApps info <andre_ponzo@differentapps.com> wrote:


(Xiaodi Wu) #9

Nice! With that explanation, I too am -1 on another way of doing the same
thing.

···

On Mon, Aug 29, 2016 at 15:53 Magnus Ahltorp via swift-evolution < swift-evolution@swift.org> wrote:

> 29 Aug. 2016 22:16 DifferentApps info <andre_ponzo@differentapps.com>
wrote:
>
> The advantage is that you do not need to define a conditional flag for
the #if.

The good news is, you don't.

#if false
  print("Disabled code")
#endif

which is a time-tested way of writing C code (using #if 0).

From the Swift changelog, where they even call it an idiom of C:

2014-04-30
[…]
* You can now use the `true` and `false` constants in build configurations,
  allowing you to emulate the C idioms of `#if 0` (but spelled `#if
false`).

One pattern I use all the time, both in C and in Swift, is this:

#if false
<experimental code>
#else
<old code>
#endif

which makes it possible to switch between the implementations quickly,
something you cannot do with the proposed syntax.

> Code disabling (with /{...}/) is a tool useful when developing
algorithm, and disabled code should not be aimed to remain definitively in
a Swift file.

Which is in no way dependent on if you use the proposed syntax,
traditional comments, or conditional compilation.

/Magnus

_______________________________________________
swift-evolution mailing list
swift-evolution@swift.org
https://lists.swift.org/mailman/listinfo/swift-evolution


(Andre Ponzo) #10

Thanks for your pattern suggestion.
But it would be also possible to switch between implementations with the proposed syntax as shown bellow:

/{
   <code 1>
}/
do {
   <code 2>
}

···

Le 29 août 2016 à 22:53, Magnus Ahltorp <map@kth.se> a écrit :

29 Aug. 2016 22:16 DifferentApps info <andre_ponzo@differentapps.com> wrote:

The advantage is that you do not need to define a conditional flag for the #if.

The good news is, you don't.

#if false
print("Disabled code")
#endif

which is a time-tested way of writing C code (using #if 0).

From the Swift changelog, where they even call it an idiom of C:

2014-04-30
[…]
* You can now use the `true` and `false` constants in build configurations,
allowing you to emulate the C idioms of `#if 0` (but spelled `#if false`).

One pattern I use all the time, both in C and in Swift, is this:

#if false
<experimental code>
#else
<old code>
#endif

which makes it possible to switch between the implementations quickly, something you cannot do with the proposed syntax.

Code disabling (with /{...}/) is a tool useful when developing algorithm, and disabled code should not be aimed to remain definitively in a Swift file.

Which is in no way dependent on if you use the proposed syntax, traditional comments, or conditional compilation.

/Magnus


(Xiaodi Wu) #11

Thanks for your pattern suggestion.
But it would be also possible to switch between implementations with the
proposed syntax as shown bellow:

/{
   <code 1>
}/
do {
   <code 2>
}

That would be greatly inferior, as you'd have to edit the code in four
distinct places, versus a single one (change #if false to #if true).

···

On Mon, Aug 29, 2016 at 4:15 PM, DifferentApps info via swift-evolution < swift-evolution@swift.org> wrote:

Le 29 août 2016 à 22:53, Magnus Ahltorp <map@kth.se> a écrit :

>> 29 Aug. 2016 22:16 DifferentApps info <andre_ponzo@differentapps.com>
wrote:
>>
>> The advantage is that you do not need to define a conditional flag for
the #if.
>
> The good news is, you don't.
>
> #if false
> print("Disabled code")
> #endif
>
> which is a time-tested way of writing C code (using #if 0).
>
> From the Swift changelog, where they even call it an idiom of C:
>
> 2014-04-30
> […]
> * You can now use the `true` and `false` constants in build
configurations,
> allowing you to emulate the C idioms of `#if 0` (but spelled `#if
false`).
>
> One pattern I use all the time, both in C and in Swift, is this:
>
> #if false
> <experimental code>
> #else
> <old code>
> #endif
>
> which makes it possible to switch between the implementations quickly,
something you cannot do with the proposed syntax.
>
>> Code disabling (with /{...}/) is a tool useful when developing
algorithm, and disabled code should not be aimed to remain definitively in
a Swift file.
>
> Which is in no way dependent on if you use the proposed syntax,
traditional comments, or conditional compilation.
>
> /Magnus
>

_______________________________________________
swift-evolution mailing list
swift-evolution@swift.org
https://lists.swift.org/mailman/listinfo/swift-evolution


(Magnus Ahltorp) #12

No, that would not be sufficient. A constructed example:

#if true
    let a : Int64
#else
    let a : Int32
#endif

Or, an actual example from some of my own code that i found (but, in this case, C-with-blocks):

#if 0
    int nrecords;
#else
    __block int nrecords;
#endif

/Magnus

···

29 Aug. 2016 23:15 DifferentApps info <andre_ponzo@differentapps.com> wrote:

Thanks for your pattern suggestion.
But it would be also possible to switch between implementations with the proposed syntax as shown bellow:

/{
  <code 1>
}/
do {
  <code 2>
}