Why not replace all Swift comments by end notes at the end of each source file so as to minimize the impact of misleading/outdated comments on code comprehension?
You don’t necessarily need to scroll to the end of the source file to read a referenced end note in the code since the IDE could show a popup whenever the mouse pointer lingers over an end note reference (e.g., a number/label).
Maybe this would encourage programmers to write more self-explanatory code while keeping (end note) comments to a minimum?
This seems like more of an IDE issue than a language issue.
- Dave Sweeris
···
On Jan 16, 2017, at 09:28, Amir Michail via swift-evolution <swift-evolution@swift.org> wrote:
Why not replace all Swift comments by end notes at the end of each source file so as to minimize the impact of misleading/outdated comments on code comprehension?
You don’t necessarily need to scroll to the end of the source file to read a referenced end note in the code since the IDE could show a popup whenever the mouse pointer lingers over an end note reference (e.g., a number/label).
Maybe this would encourage programmers to write more self-explanatory code while keeping (end note) comments to a minimum?
As a general rule of thumb, changes to the language should not require the
use of an IDE in order to return them back to the level of usability that
was had before the change. Swift is not a Mac/Xcode-only language, and even
on that platform, there are a number of times where I personally find
myself working in Sublime Text instead of Xcode, for various reasons.
Regarding this idea specifically, I think it would simply discourage users
from writing comments at all, without necessarily any improvement in code
quality. The developers who already write self-explanatory code will
continue to do so, and those who write bad code and don't comment will also
continue to do so. Do you have any evidence that making commenting harder
would improve code quality?
···
On Mon, Jan 16, 2017 at 7:28 AM Amir Michail via swift-evolution < swift-evolution@swift.org> wrote:
Why not replace all Swift comments by end notes at the end of each source
file so as to minimize the impact of misleading/outdated comments on code
comprehension?
You don’t necessarily need to scroll to the end of the source file to read
a referenced end note in the code since the IDE could show a popup whenever
the mouse pointer lingers over an end note reference (e.g., a number/label).
Maybe this would encourage programmers to write more self-explanatory code
while keeping (end note) comments to a minimum?
_______________________________________________
swift-evolution mailing list
swift-evolution@swift.org https://lists.swift.org/mailman/listinfo/swift-evolution
2017/01/16 10:28、Amir Michail via swift-evolution <swift-evolution@swift.org> のメッセージ:
Why not replace all Swift comments by end notes at the end of each source file so as to minimize the impact of misleading/outdated comments on code comprehension?
The location of code comments was never the issue.
You don’t necessarily need to scroll to the end of the source file to read a referenced end note in the code since the IDE could show a popup whenever the mouse pointer lingers over an end note reference (e.g., a number/label).
As others have noted, it is really not a good idea to introduce features predicated on the existence of Xcode.
Maybe this would encourage programmers to write more self-explanatory code while keeping (end note) comments to a minimum?
This seems like it is just going to encourage a huge unmaintainable book being written at the end of every file. The ratio of documentation to code in some libraries is 10-or-20-to-1 in some cases.
It seems like this proposal has a scaling problem.
Why not replace all Swift comments by end notes at the end of each source file so as to minimize the impact of misleading/outdated comments on code comprehension?
A strong -1 from me. Moving comments aside from the place where the code is defined is going to maximise outdated comments, not minimise it.
You don’t necessarily need to scroll to the end of the source file to read a referenced end note in the code since the IDE could show a popup whenever the mouse pointer lingers over an end note reference (e.g., a number/label).
Maybe this would encourage programmers to write more self-explanatory code while keeping (end note) comments to a minimum?
This proposal would certainly discourage having accurate comments.
Alex
···
On 16 Jan 2017, at 15:28, Amir Michail via swift-evolution <swift-evolution@swift.org> wrote:
As a general rule of thumb, changes to the language should not require the use of an IDE in order to return them back to the level of usability that was had before the change. Swift is not a Mac/Xcode-only language, and even on that platform, there are a number of times where I personally find myself working in Sublime Text instead of Xcode, for various reasons.
One could argue that those using a simple editor that can't hide comments would benefit more from this proposal.
···
On Jan 16, 2017, at 10:55 AM, Tony Allevato <tony.allevato@gmail.com> wrote:
Regarding this idea specifically, I think it would simply discourage users from writing comments at all, without necessarily any improvement in code quality. The developers who already write self-explanatory code will continue to do so, and those who write bad code and don't comment will also continue to do so. Do you have any evidence that making commenting harder would improve code quality?
On Mon, Jan 16, 2017 at 7:28 AM Amir Michail via swift-evolution <swift-evolution@swift.org> wrote:
Why not replace all Swift comments by end notes at the end of each source file so as to minimize the impact of misleading/outdated comments on code comprehension?
You don’t necessarily need to scroll to the end of the source file to read a referenced end note in the code since the IDE could show a popup whenever the mouse pointer lingers over an end note reference (e.g., a number/label).
Maybe this would encourage programmers to write more self-explanatory code while keeping (end note) comments to a minimum?
_______________________________________________
swift-evolution mailing list
swift-evolution@swift.org https://lists.swift.org/mailman/listinfo/swift-evolution
>
> As a general rule of thumb, changes to the language should not require
the use of an IDE in order to return them back to the level of usability
that was had before the change. Swift is not a Mac/Xcode-only language, and
even on that platform, there are a number of times where I personally find
myself working in Sublime Text instead of Xcode, for various reasons.
>
One could argue that those using a simple editor that can't hide comments
would benefit more from this proposal.
By removing the context that those comments can provide? It seems like
you're trying to argue both sides of an argument at the same time: this
feature is OK because IDEs can still show you the comments and you don't
have to scroll to the end of the file, but users without IDEs who will be
forced to scroll to the end of the file will still benefit because...?
It feels like your argument is just that comments can become out of date,
or they take up too much space/you want to see more of the code. For the
first, that's a problem that your proposal won't solve—it just moves the
outdated content to the end of the file where it can be ignored more
easily. That's not an improvement. For the second, I think most software
developers would *love* to have the problem of too much documentation in
their code vs. too little. :)
···
On Mon, Jan 16, 2017 at 8:38 AM Amir Michail <a.michail@me.com> wrote:
> On Jan 16, 2017, at 10:55 AM, Tony Allevato <tony.allevato@gmail.com> > wrote:
> Regarding this idea specifically, I think it would simply discourage
users from writing comments at all, without necessarily any improvement in
code quality. The developers who already write self-explanatory code will
continue to do so, and those who write bad code and don't comment will also
continue to do so. Do you have any evidence that making commenting harder
would improve code quality?
>
> On Mon, Jan 16, 2017 at 7:28 AM Amir Michail via swift-evolution < > swift-evolution@swift.org> wrote:
> Why not replace all Swift comments by end notes at the end of each
source file so as to minimize the impact of misleading/outdated comments on
code comprehension?
>
> You don’t necessarily need to scroll to the end of the source file to
read a referenced end note in the code since the IDE could show a popup
whenever the mouse pointer lingers over an end note reference (e.g., a
number/label).
>
> Maybe this would encourage programmers to write more self-explanatory
code while keeping (end note) comments to a minimum?
> _______________________________________________
> swift-evolution mailing list
> swift-evolution@swift.org
> https://lists.swift.org/mailman/listinfo/swift-evolution
As a general rule of thumb, changes to the language should not require the use of an IDE in order to return them back to the level of usability that was had before the change. Swift is not a Mac/Xcode-only language, and even on that platform, there are a number of times where I personally find myself working in Sublime Text instead of Xcode, for various reasons.
One could argue that those using a simple editor that can't hide comments would benefit more from this proposal.
Not really, unless you work with code that you are very familiar with. Imagine jumping up and down a 1000 LOC file and looking up what a method does. That's fairly insane...
···
On Jan 16, 2017, at 5:38 PM, Amir Michail via swift-evolution <swift-evolution@swift.org> wrote:
On Jan 16, 2017, at 10:55 AM, Tony Allevato <tony.allevato@gmail.com> wrote:
Regarding this idea specifically, I think it would simply discourage users from writing comments at all, without necessarily any improvement in code quality. The developers who already write self-explanatory code will continue to do so, and those who write bad code and don't comment will also continue to do so. Do you have any evidence that making commenting harder would improve code quality?
On Mon, Jan 16, 2017 at 7:28 AM Amir Michail via swift-evolution <swift-evolution@swift.org> wrote:
Why not replace all Swift comments by end notes at the end of each source file so as to minimize the impact of misleading/outdated comments on code comprehension?
You don’t necessarily need to scroll to the end of the source file to read a referenced end note in the code since the IDE could show a popup whenever the mouse pointer lingers over an end note reference (e.g., a number/label).
Maybe this would encourage programmers to write more self-explanatory code while keeping (end note) comments to a minimum?
_______________________________________________
swift-evolution mailing list
swift-evolution@swift.org https://lists.swift.org/mailman/listinfo/swift-evolution
Although, that said, I just tried doing it in Xcode and it didn’t fold my ///-style documentation comments or multi-line /*…*/-style comment blocks. Possibly a bug in SourceKit?
- Karl
···
On 16 Jan 2017, at 20:26, David Sweeris via swift-evolution <swift-evolution@swift.org> wrote:
On Jan 16, 2017, at 09:28, Amir Michail via swift-evolution <swift-evolution@swift.org> wrote:
Why not replace all Swift comments by end notes at the end of each source file so as to minimize the impact of misleading/outdated comments on code comprehension?
You don’t necessarily need to scroll to the end of the source file to read a referenced end note in the code since the IDE could show a popup whenever the mouse pointer lingers over an end note reference (e.g., a number/label).
Maybe this would encourage programmers to write more self-explanatory code while keeping (end note) comments to a minimum?
This seems like more of an IDE issue than a language issue.
I don’t understand. Why would I want to hide the comments?
···
On 16 Jan 2017, at 16:38, Amir Michail via swift-evolution <swift-evolution@swift.org> wrote:
On Jan 16, 2017, at 10:55 AM, Tony Allevato <tony.allevato@gmail.com> wrote:
As a general rule of thumb, changes to the language should not require the use of an IDE in order to return them back to the level of usability that was had before the change. Swift is not a Mac/Xcode-only language, and even on that platform, there are a number of times where I personally find myself working in Sublime Text instead of Xcode, for various reasons.
One could argue that those using a simple editor that can't hide comments would benefit more from this proposal.
On 17 Jan 2017, at 12:30, Alex Blewitt via swift-evolution <swift-evolution@swift.org> wrote:
On 16 Jan 2017, at 15:28, Amir Michail via swift-evolution <swift-evolution@swift.org> wrote:
Why not replace all Swift comments by end notes at the end of each source file so as to minimize the impact of misleading/outdated comments on code comprehension?
A strong -1 from me. Moving comments aside from the place where the code is defined is going to maximise outdated comments, not minimise it.
You don’t necessarily need to scroll to the end of the source file to read a referenced end note in the code since the IDE could show a popup whenever the mouse pointer lingers over an end note reference (e.g., a number/label).
Maybe this would encourage programmers to write more self-explanatory code while keeping (end note) comments to a minimum?
This proposal would certainly discourage having accurate comments.
Why not replace all Swift comments by end notes at the end of each source file so as to minimize the impact of misleading/outdated comments on code comprehension?
You don’t necessarily need to scroll to the end of the source file to read a referenced end note in the code since the IDE could show a popup whenever the mouse pointer lingers over an end note reference (e.g., a number/label).
Maybe this would encourage programmers to write more self-explanatory code while keeping (end note) comments to a minimum?
This seems like more of an IDE issue than a language issue.
Most IDEs can do a lot of stuff Xcode can't. Unfortunately.
···
On Jan 16, 2017, at 8:29 PM, Karl Wagner via swift-evolution <swift-evolution@swift.org> wrote:
On 16 Jan 2017, at 20:26, David Sweeris via swift-evolution <swift-evolution@swift.org> wrote:
On Jan 16, 2017, at 09:28, Amir Michail via swift-evolution <swift-evolution@swift.org> wrote:
Although, that said, I just tried doing it in Xcode and it didn’t fold my ///-style documentation comments or multi-line /*…*/-style comment blocks. Possibly a bug in SourceKit?
-1 from me. I prefer at-site documentation rather than having to scroll through potentially hundreds of comments at the end of the file (each of which would then have to have additional data to provide context information that isn't needed as it currently stands.
I fully understand (and agree) how not being able to fold comments, especially Foundations doc comments is annoying (It's very frustrating to scroll through a doc comment 3x the length of the function itself), but that's an editor issue, not a Swift one.
If you want to write all your comments as end notes, there is nothing stopping you, but I extremely doubt that such a proposal would be accepted, sorry.
-thislooksfun (tlf)
···
On Jan 16, 2017, at 1:34 PM, Charlie Monroe via swift-evolution <swift-evolution@swift.org> wrote:
On Jan 16, 2017, at 8:29 PM, Karl Wagner via swift-evolution <swift-evolution@swift.org> wrote:
On 16 Jan 2017, at 20:26, David Sweeris via swift-evolution <swift-evolution@swift.org> wrote:
On Jan 16, 2017, at 09:28, Amir Michail via swift-evolution <swift-evolution@swift.org> wrote:
Why not replace all Swift comments by end notes at the end of each source file so as to minimize the impact of misleading/outdated comments on code comprehension?
You don’t necessarily need to scroll to the end of the source file to read a referenced end note in the code since the IDE could show a popup whenever the mouse pointer lingers over an end note reference (e.g., a number/label).
Maybe this would encourage programmers to write more self-explanatory code while keeping (end note) comments to a minimum?
This seems like more of an IDE issue than a language issue.
Most IDEs can do a lot of stuff Xcode can't. Unfortunately.
Although, that said, I just tried doing it in Xcode and it didn’t fold my ///-style documentation comments or multi-line /*…*/-style comment blocks. Possibly a bug in SourceKit?