Code comments that check code validity.


(Amir Michail) #1

The code in a “code comment" must compile (not just be syntactically correct) yet must not have any effect on the resulting executable.

For example, commented entries in an array would be checked for compilability but would not be included in the executable.

Such “code comments" would allow you to have code/data that is currently unused but is constantly checked to be valid just in case you want to use it in the future.


(Xiaodi Wu) #2

This has been brought up on this list before. The conclusion of the
previous thread on this topic was that there is a way to do this:

#if false
// put your code here
#endif

It does not allow you to comment out fragments of a single statement, but
the incremental value of devoting time to additionally support that is, it
would seem, low.

···

On Sat, Jan 14, 2017 at 17:18 Amir Michail via swift-evolution < swift-evolution@swift.org> wrote:

The code in a “code comment" must compile (not just be syntactically
correct) yet must not have any effect on the resulting executable.

For example, commented entries in an array would be checked for
compilability but would not be included in the executable.

Such “code comments" would allow you to have code/data that is currently
unused but is constantly checked to be valid just in case you want to use
it in the future.

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


(Robert Widmann) #3

Some thoughts, inline

~Robert Widmann

2017/01/14 18:18、Amir Michail via swift-evolution <swift-evolution@swift.org> のメッセージ:

The code in a “code comment" must compile (not just be syntactically correct) yet must not have any effect on the resulting executable.

What is the definition of "compile"? It truly matters because certain definitions you give will have serious security threats associated with them.

There's also a certain style of linter tool that is built for running code in documentation to check its correctness (Scala has a famous one in the form of Tut (https://github.com/tpolecat/tut). Tut spins up individual REPL sessions per comment so is built to be run as a commit hook or as part of CI builds, not something live (a bit like a miniature playground) running inside the IDE. On the other hand, for the majority of code comments it probably suffices to just get it through typechecking. You won't have the benefit of checking its execution, but at least you'll know you have some well-formed code in the comment.

For example, commented entries in an array would be checked for compilability but would not be included in the executable.

We suddenly have to demarcate which parts of the language are "safe" versus "unsafe" is what you mean? This sounds incredibly brittle and borderline unenforceable.

Such “code comments" would allow you to have code/data that is currently unused but is constantly checked to be valid just in case you want to use it in the future.

There is a way to go about doing this in a safe and productive manner, but it may not quite be the way you see it in your minds' eye. If you want code execution you have to trade in security. If you want live/quick results you have to give up execution. Lord knows we don't need malicious comments to be the source of the next Xcode Ghost nor do we need to slow the IDE to a crawl checking a thousand comment sheds in a thousand REPL sessions.

···

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


(Haravikk) #4

I think I'm opposed to this; I believe we have enough options for this already, no need to have code comments as well.

Options include:

1. Putting code in conditionals that use final/constant values (i.e- compiled away when value evaluates as false)
2. Unused closures/methods/functions
3. Assertions (and the code they call), since these compile away in production code.
4. Polymorphism/generics, useful for swapping in stub or otherwise dummy types when you want to test others in isolation. Or even just to keep around an older version of an implementation, handy if you reimplement something for performance, but thing you might have a subtle bug an older version didn't have.

I'd argue that leaving code in comments is bad practice with better alternatives, so supporting it more could be counterproductive. The only places I use code comments are when I replace a complex line of code, but want to leave it in position as a reminder of what the original code did (in case the new code is different somehow), but even then I leave it as a FIXME to remind me to remove it once I'm happy with my tests.

I dunno, I just feel like we've got better tools for handling old/conditional code already.

···

On 14 Jan 2017, at 23:18, Amir Michail via swift-evolution <swift-evolution@swift.org> wrote:

The code in a “code comment" must compile (not just be syntactically correct) yet must not have any effect on the resulting executable.

For example, commented entries in an array would be checked for compilability but would not be included in the executable.

Such “code comments" would allow you to have code/data that is currently unused but is constantly checked to be valid just in case you want to use it in the future.

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


(Xiaodi Wu) #5

>
> This has been brought up on this list before. The conclusion of the
previous thread on this topic was that there is a way to do this:
>
> #if false
> // put your code here
> #endif
>

This would not check the code for compilability within the surrounding
code. This requires more than a syntax check.

I can't say I've ever needed that feature; could you share a concrete use
case?

In any case, if you put code in a function that's not exported and never
invoked, I believe you would achieve the desired effect. Within the body of
a function, you could do so in a closure.

func foo() {
  // code you want to run
  _ = {
    // code you don't intend to run
  }
  // more code you want to run
}
···

On Sat, Jan 14, 2017 at 5:35 PM, Amir Michail <a.michail@me.com> wrote:

> On Jan 14, 2017, at 6:28 PM, Xiaodi Wu <xiaodi.wu@gmail.com> wrote:

It does not allow you to comment out fragments of a single statement, but
the incremental value of devoting time to additionally support that is, it
would seem, low.
>
> On Sat, Jan 14, 2017 at 17:18 Amir Michail via swift-evolution < > swift-evolution@swift.org> wrote:
> The code in a “code comment" must compile (not just be syntactically
correct) yet must not have any effect on the resulting executable.
>
> For example, commented entries in an array would be checked for
compilability but would not be included in the executable.
>
> Such “code comments" would allow you to have code/data that is currently
unused but is constantly checked to be valid just in case you want to use
it in the future.
>
> _______________________________________________
> swift-evolution mailing list
> swift-evolution@swift.org
> https://lists.swift.org/mailman/listinfo/swift-evolution


(Xiaodi Wu) #6
enum Levels: Int {
  case foo = 1, bar, baz, boo
}

var levels: [Levels] = [
  .foo,
  .bar,
]

// disabled
_ = {
  levels += [
    .baz,
    .boo,
    // this won't compile if you add:
    // .nonExistent,
  ]
}
···

On Sat, Jan 14, 2017 at 5:50 PM, Amir Michail <a.michail@me.com> wrote:

On Jan 14, 2017, at 6:46 PM, Xiaodi Wu <xiaodi.wu@gmail.com> wrote:

On Sat, Jan 14, 2017 at 5:35 PM, Amir Michail <a.michail@me.com> wrote:

> On Jan 14, 2017, at 6:28 PM, Xiaodi Wu <xiaodi.wu@gmail.com> wrote:
>
> This has been brought up on this list before. The conclusion of the
previous thread on this topic was that there is a way to do this:
>
> #if false
> // put your code here
> #endif
>

This would not check the code for compilability within the surrounding
code. This requires more than a syntax check.

I can't say I've ever needed that feature; could you share a concrete use
case?

Consider an array of levels for a game where some levels are commented out
for possible future use. It would be nice to have such level entries
continue to compile as the code elsewhere evolves and yet not be included
in the executable.


(Amir Michail) #7

This has been brought up on this list before. The conclusion of the previous thread on this topic was that there is a way to do this:

#if false
// put your code here
#endif

This would not check the code for compilability within the surrounding code. This requires more than a syntax check.

···

On Jan 14, 2017, at 6:28 PM, Xiaodi Wu <xiaodi.wu@gmail.com> wrote:

It does not allow you to comment out fragments of a single statement, but the incremental value of devoting time to additionally support that is, it would seem, low.

On Sat, Jan 14, 2017 at 17:18 Amir Michail via swift-evolution <swift-evolution@swift.org> wrote:
The code in a “code comment" must compile (not just be syntactically correct) yet must not have any effect on the resulting executable.

For example, commented entries in an array would be checked for compilability but would not be included in the executable.

Such “code comments" would allow you to have code/data that is currently unused but is constantly checked to be valid just in case you want to use it in the future.

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


(Amir Michail) #8

>
> This has been brought up on this list before. The conclusion of the previous thread on this topic was that there is a way to do this:
>
> #if false
> // put your code here
> #endif
>

This would not check the code for compilability within the surrounding code. This requires more than a syntax check.

I can't say I've ever needed that feature; could you share a concrete use case?

Consider an array of levels for a game where some levels are commented out for possible future use. It would be nice to have such level entries continue to compile as the code elsewhere evolves and yet not be included in the executable.

···

On Jan 14, 2017, at 6:46 PM, Xiaodi Wu <xiaodi.wu@gmail.com> wrote:
On Sat, Jan 14, 2017 at 5:35 PM, Amir Michail <a.michail@me.com <mailto:a.michail@me.com>> wrote:
> On Jan 14, 2017, at 6:28 PM, Xiaodi Wu <xiaodi.wu@gmail.com <mailto:xiaodi.wu@gmail.com>> wrote:

In any case, if you put code in a function that's not exported and never invoked, I believe you would achieve the desired effect. Within the body of a function, you could do so in a closure.

func foo() {
  // code you want to run
  _ = {
    // code you don't intend to run
  }
  // more code you want to run
}

> It does not allow you to comment out fragments of a single statement, but the incremental value of devoting time to additionally support that is, it would seem, low.
>
> On Sat, Jan 14, 2017 at 17:18 Amir Michail via swift-evolution <swift-evolution@swift.org <mailto:swift-evolution@swift.org>> wrote:
> The code in a “code comment" must compile (not just be syntactically correct) yet must not have any effect on the resulting executable.
>
> For example, commented entries in an array would be checked for compilability but would not be included in the executable.
>
> Such “code comments" would allow you to have code/data that is currently unused but is constantly checked to be valid just in case you want to use it in the future.
>
> _______________________________________________
> swift-evolution mailing list
> swift-evolution@swift.org <mailto:swift-evolution@swift.org>
> https://lists.swift.org/mailman/listinfo/swift-evolution


(Amir Michail) #9

That’s helpful thanks! I still think code comments would be nice though.

···

On Jan 14, 2017, at 6:56 PM, Xiaodi Wu <xiaodi.wu@gmail.com> wrote:

On Sat, Jan 14, 2017 at 5:50 PM, Amir Michail <a.michail@me.com <mailto:a.michail@me.com>> wrote:

On Jan 14, 2017, at 6:46 PM, Xiaodi Wu <xiaodi.wu@gmail.com <mailto:xiaodi.wu@gmail.com>> wrote:

On Sat, Jan 14, 2017 at 5:35 PM, Amir Michail <a.michail@me.com <mailto:a.michail@me.com>> wrote:

> On Jan 14, 2017, at 6:28 PM, Xiaodi Wu <xiaodi.wu@gmail.com <mailto:xiaodi.wu@gmail.com>> wrote:
>
> This has been brought up on this list before. The conclusion of the previous thread on this topic was that there is a way to do this:
>
> #if false
> // put your code here
> #endif
>

This would not check the code for compilability within the surrounding code. This requires more than a syntax check.

I can't say I've ever needed that feature; could you share a concrete use case?

Consider an array of levels for a game where some levels are commented out for possible future use. It would be nice to have such level entries continue to compile as the code elsewhere evolves and yet not be included in the executable.

enum Levels: Int {
  case foo = 1, bar, baz, boo
}

var levels: [Levels] = [
  .foo,
  .bar,
]

// disabled
_ = {
  levels += [
    .baz,
    .boo,
    // this won't compile if you add:
    // .nonExistent,
  ]
}

(Jay) #10

I think this would be an anti-feature , here are some reasons why:

   - If it is code you wrote as an idea for how something might be
   implemented in the future, then it should be manually tweaked/validated
   anyway when you put it back in. If things change slightly such that your
   old commented code breaks when you comment it back in this is a good thing,
   it forces you to check/amend the old code so that it functions properly in
   the updated environment that it now inhabits.
   - If it’s a significant amount of code then it really ought to be
   structured into something appropriate, like a function or a class, in which
   case it can happily live uncalled and not commented out. But it’s not a
   great practice to leave unused code lying around, unless you know it’s
   going to be used soon.
   - Commented code is often commented out specifically to make things
   compile while you tweak/break things somewhere else (i.e. commented out
   temporarily) - so of course you don’t want it to be compiled.
   - If you comment out code temporarily then it really should just mean
   temporarily, i.e. between now and your next commit to test something
   immediately. Source control means there’s no need for longer-lived
   commented out code. Unfinished code can live on a branch, old code that you
   might want to refer to or re-use later is in your source control history,
   and unused code should probably just be removed.
   - Code that is written and working and intended to be enabled later on
   should be activated by a feature-toggle (either a compile-time or a
   run-time one) rather than commented out.

···

On Sun, 15 Jan 2017 at 00:04 Amir Michail via swift-evolution < swift-evolution@swift.org> wrote:

On Jan 14, 2017, at 6:56 PM, Xiaodi Wu <xiaodi.wu@gmail.com> wrote:

On Sat, Jan 14, 2017 at 5:50 PM, Amir Michail <a.michail@me.com> wrote:

On Jan 14, 2017, at 6:46 PM, Xiaodi Wu <xiaodi.wu@gmail.com> wrote:

On Sat, Jan 14, 2017 at 5:35 PM, Amir Michail <a.michail@me.com> wrote:

> On Jan 14, 2017, at 6:28 PM, Xiaodi Wu <xiaodi.wu@gmail.com> wrote:
>
> This has been brought up on this list before. The conclusion of the
previous thread on this topic was that there is a way to do this:
>
> #if false
> // put your code here
> #endif
>

This would not check the code for compilability within the surrounding
code. This requires more than a syntax check.

I can't say I've ever needed that feature; could you share a concrete use
case?

Consider an array of levels for a game where some levels are commented out
for possible future use. It would be nice to have such level entries
continue to compile as the code elsewhere evolves and yet not be included
in the executable.

enum Levels: Int {
  case foo = 1, bar, baz, boo
}

var levels: [Levels] = [
  .foo,
  .bar,
]

// disabled
_ = {
  levels += [
    .baz,
    .boo,
    // this won't compile if you add:
    // .nonExistent,
  ]
}

That’s helpful thanks! I still think code comments would be nice though.

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


(Amir Michail) #11

I think this would be an anti-feature , here are some reasons why:

  • If it is code you wrote as an idea for how something might be implemented in the future, then it should be manually tweaked/validated anyway when you put it back in. If things change slightly such that your old commented code breaks when you comment it back in this is a good thing, it forces you to check/amend the old code so that it functions properly in the updated environment that it now inhabits.
  • If it’s a significant amount of code then it really ought to be structured into something appropriate, like a function or a class, in which case it can happily live uncalled and not commented out. But it’s not a great practice to leave unused code lying around, unless you know it’s going to be used soon.
  • Commented code is often commented out specifically to make things compile while you tweak/break things somewhere else (i.e. commented out temporarily) - so of course you don’t want it to be compiled.
  • If you comment out code temporarily then it really should just mean temporarily, i.e. between now and your next commit to test something immediately. Source control means there’s no need for longer-lived commented out code. Unfinished code can live on a branch, old code that you might want to refer to or re-use later is in your source control history, and unused code should probably just be removed.

Other developers may prefer to have some code comments. Solo indie developers have more freedom to just do what they want in this respect...

···

On Jan 14, 2017, at 8:11 PM, Jay Abbott <jay@abbott.me.uk> wrote:

  • Code that is written and working and intended to be enabled later on should be activated by a feature-toggle (either a compile-time or a run-time one) rather than commented out.

On Sun, 15 Jan 2017 at 00:04 Amir Michail via swift-evolution <swift-evolution@swift.org> wrote:

On Jan 14, 2017, at 6:56 PM, Xiaodi Wu <xiaodi.wu@gmail.com> wrote:

On Sat, Jan 14, 2017 at 5:50 PM, Amir Michail <a.michail@me.com> wrote:

On Jan 14, 2017, at 6:46 PM, Xiaodi Wu <xiaodi.wu@gmail.com> wrote:

On Sat, Jan 14, 2017 at 5:35 PM, Amir Michail <a.michail@me.com> wrote:

> On Jan 14, 2017, at 6:28 PM, Xiaodi Wu <xiaodi.wu@gmail.com> wrote:
>
> This has been brought up on this list before. The conclusion of the previous thread on this topic was that there is a way to do this:
>
> #if false
> // put your code here
> #endif
>

This would not check the code for compilability within the surrounding code. This requires more than a syntax check.

I can't say I've ever needed that feature; could you share a concrete use case?

Consider an array of levels for a game where some levels are commented out for possible future use. It would be nice to have such level entries continue to compile as the code elsewhere evolves and yet not be included in the executable.

enum Levels: Int {
  case foo = 1, bar, baz, boo
}

var levels: [Levels] = [
  .foo,
  .bar,
]

// disabled
_ = {
  levels += [
    .baz,
    .boo,
    // this won't compile if you add:
    // .nonExistent,
  ]
}

That’s helpful thanks! I still think code comments would be nice though.

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


(Step C) #12

These (maintaining a clean codebase, using source control, branching) are good practices for solo developers as much as anyone else.

···

El ene. 15, 2017, a las 2:24 PM, Amir Michail via swift-evolution <swift-evolution@swift.org> escribió:

On Jan 14, 2017, at 8:11 PM, Jay Abbott <jay@abbott.me.uk> wrote:

I think this would be an anti-feature , here are some reasons why:

   • If it is code you wrote as an idea for how something might be implemented in the future, then it should be manually tweaked/validated anyway when you put it back in. If things change slightly such that your old commented code breaks when you comment it back in this is a good thing, it forces you to check/amend the old code so that it functions properly in the updated environment that it now inhabits.
   • If it’s a significant amount of code then it really ought to be structured into something appropriate, like a function or a class, in which case it can happily live uncalled and not commented out. But it’s not a great practice to leave unused code lying around, unless you know it’s going to be used soon.
   • Commented code is often commented out specifically to make things compile while you tweak/break things somewhere else (i.e. commented out temporarily) - so of course you don’t want it to be compiled.
   • If you comment out code temporarily then it really should just mean temporarily, i.e. between now and your next commit to test something immediately. Source control means there’s no need for longer-lived commented out code. Unfinished code can live on a branch, old code that you might want to refer to or re-use later is in your source control history, and unused code should probably just be removed.

Other developers may prefer to have some code comments. Solo indie developers have more freedom to just do what they want in this respect...

   • Code that is written and working and intended to be enabled later on should be activated by a feature-toggle (either a compile-time or a run-time one) rather than commented out.

On Sun, 15 Jan 2017 at 00:04 Amir Michail via swift-evolution <swift-evolution@swift.org> wrote:

On Jan 14, 2017, at 6:56 PM, Xiaodi Wu <xiaodi.wu@gmail.com> wrote:

On Sat, Jan 14, 2017 at 5:50 PM, Amir Michail <a.michail@me.com> wrote:

On Jan 14, 2017, at 6:46 PM, Xiaodi Wu <xiaodi.wu@gmail.com> wrote:

On Sat, Jan 14, 2017 at 5:35 PM, Amir Michail <a.michail@me.com> wrote:

On Jan 14, 2017, at 6:28 PM, Xiaodi Wu <xiaodi.wu@gmail.com> wrote:

This has been brought up on this list before. The conclusion of the previous thread on this topic was that there is a way to do this:

#if false
// put your code here
#endif

This would not check the code for compilability within the surrounding code. This requires more than a syntax check.

I can't say I've ever needed that feature; could you share a concrete use case?

Consider an array of levels for a game where some levels are commented out for possible future use. It would be nice to have such level entries continue to compile as the code elsewhere evolves and yet not be included in the executable.

enum Levels: Int {
 case foo = 1, bar, baz, boo
}

var levels: [Levels] = [
 .foo,
 .bar,
]

// disabled
_ = {
 levels += [
   .baz,
   .boo,
   // this won't compile if you add:
   // .nonExistent,
 ]
}

That’s helpful thanks! I still think code comments would be nice though.

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

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


(Pierre Monod-Broca) #13

Amir's idea is interesting to me.
But I like Xiadi's solution with unused closure, and I don't see a reason to put more effort into this.

It works well with simple and complex cases, and anyhow, for complex cases, feature switches and/or branches are already suitable, like said before.

Pierre

···

Le 16 janv. 2017 à 06:39, Step Christopher via swift-evolution <swift-evolution@swift.org> a écrit :

These (maintaining a clean codebase, using source control, branching) are good practices for solo developers as much as anyone else.

El ene. 15, 2017, a las 2:24 PM, Amir Michail via swift-evolution <swift-evolution@swift.org> escribió:

On Jan 14, 2017, at 8:11 PM, Jay Abbott <jay@abbott.me.uk> wrote:

I think this would be an anti-feature , here are some reasons why:

  • If it is code you wrote as an idea for how something might be implemented in the future, then it should be manually tweaked/validated anyway when you put it back in. If things change slightly such that your old commented code breaks when you comment it back in this is a good thing, it forces you to check/amend the old code so that it functions properly in the updated environment that it now inhabits.
  • If it’s a significant amount of code then it really ought to be structured into something appropriate, like a function or a class, in which case it can happily live uncalled and not commented out. But it’s not a great practice to leave unused code lying around, unless you know it’s going to be used soon.
  • Commented code is often commented out specifically to make things compile while you tweak/break things somewhere else (i.e. commented out temporarily) - so of course you don’t want it to be compiled.
  • If you comment out code temporarily then it really should just mean temporarily, i.e. between now and your next commit to test something immediately. Source control means there’s no need for longer-lived commented out code. Unfinished code can live on a branch, old code that you might want to refer to or re-use later is in your source control history, and unused code should probably just be removed.

Other developers may prefer to have some code comments. Solo indie developers have more freedom to just do what they want in this respect...

  • Code that is written and working and intended to be enabled later on should be activated by a feature-toggle (either a compile-time or a run-time one) rather than commented out.

On Sun, 15 Jan 2017 at 00:04 Amir Michail via swift-evolution <swift-evolution@swift.org> wrote:

On Jan 14, 2017, at 6:56 PM, Xiaodi Wu <xiaodi.wu@gmail.com> wrote:

On Sat, Jan 14, 2017 at 5:50 PM, Amir Michail <a.michail@me.com> wrote:

On Jan 14, 2017, at 6:46 PM, Xiaodi Wu <xiaodi.wu@gmail.com> wrote:

On Sat, Jan 14, 2017 at 5:35 PM, Amir Michail <a.michail@me.com> wrote:

On Jan 14, 2017, at 6:28 PM, Xiaodi Wu <xiaodi.wu@gmail.com> wrote:

This has been brought up on this list before. The conclusion of the previous thread on this topic was that there is a way to do this:

#if false
// put your code here
#endif

This would not check the code for compilability within the surrounding code. This requires more than a syntax check.

I can't say I've ever needed that feature; could you share a concrete use case?

Consider an array of levels for a game where some levels are commented out for possible future use. It would be nice to have such level entries continue to compile as the code elsewhere evolves and yet not be included in the executable.

enum Levels: Int {
case foo = 1, bar, baz, boo
}

var levels: [Levels] = [
.foo,
.bar,
]

// disabled
_ = {
levels += [
  .baz,
  .boo,
  // this won't compile if you add:
  // .nonExistent,
]
}

That’s helpful thanks! I still think code comments would be nice though.

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

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

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