[swift-evolution] [Proposal] Replace all Swift comments by end notes.

[thislooksfun]

-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 at swift.org> wrote:
> 
>> 
>> On Jan 16, 2017, at 8:29 PM, Karl Wagner via swift-evolution <swift-evolution at swift.org> wrote:
>> 
>> 
>>> On 16 Jan 2017, at 20:26, David Sweeris via swift-evolution <swift-evolution at swift.org> wrote:
>>> 
>>> 
>>> 
>>>> On Jan 16, 2017, at 09:28, Amir Michail via swift-evolution <swift-evolution at 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.
>>> 
>>> - Dave Sweeris 
>>> _______________________________________________
>>> swift-evolution mailing list
>>> swift-evolution at swift.org
>>> https://lists.swift.org/mailman/listinfo/swift-evolution
>> 
>> Most IDEs can fold comment blocks, can’t they?
> 
> 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?
>> 
>> - Karl
>> _______________________________________________
>> swift-evolution mailing list
>> swift-evolution at swift.org <mailto:swift-evolution at swift.org>
>> https://lists.swift.org/mailman/listinfo/swift-evolution <https://lists.swift.org/mailman/listinfo/swift-evolution>
> 
> _______________________________________________
> swift-evolution mailing list
> swift-evolution at swift.org <mailto:swift-evolution at swift.org>
> https://lists.swift.org/mailman/listinfo/swift-evolution <https://lists.swift.org/mailman/listinfo/swift-evolution>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.swift.org/pipermail/swift-evolution/attachments/20170116/c2fe8d87/attachment.html>