[amadeuspagel]

The fundamental issue with comments in programming is that they're part of the code, which is a ridiculous hack that somehow survives unquestioned. This is not how comments work in Google Docs, Microsoft Word, etc.. Maybe the idea of implementing comments as a greyed out part of the main text did not occur to the designers of these apps?

[the_af]

Counterpoint: keeping comments in the code results in a simpler format (just plain text, which is battle-tested and requires no special tools or lock-in) and it keeps the comments next to their context.

I find Google Docs comments hard to find and navigate, and usually simply forget to read them. A usability nightmare for me.

[marcosdumay]

The is not the natural state of things. That's also not the original state of things.

For the decades that software engineering has existed, people have been busy migrating more and more information from offline in a different context into inline right at the code. Every single one of those times, people have experienced huge gains on the quality of the resulting comments, with moderate gains on project organization and productivity.

So, the reason comments are a greyed text inline with the code is that it has worked better. Having the comments offline (like software used to have) is very likely a flaw of those platforms. But well, the text-creation people never looked at improving their tooling anyway.

[amadeuspagel]

Different context meaning random chats and mailing lists, not an integrated system like Google Docs or Microsoft Word.

[marcosdumay]

Different contexts meaning integrated systems, official documentation repositories, parallel files included with the code, and well, almost everything you can think of.

People have not spent those decades doing nothing. They tried a huge diversity of stuff.

[tuyiown]

That's an interesting take.

Especially that more and more toolchain always comments with formatted contents to runnable example snippet that can be checked by tests, that can be extracted and formatted to be consulted otherwise.

I suspect that the common use of greying it out is that it's hard to concentrate to both code and reading comments, the priority given to code and remove distraction.

Maybe there's a dedicated UI to invent, something that would even more remove comment distraction to just indicate their presence, and provide a handy access to the content in a nicely formatted way without disturbing the main code view.

[arp242]

The default Vim colourscheme has comments in blue, and they stand out rather than fade away. I don't know if Vim is an exception or if this sort of thing was more common in the past, but this always seemed right to me (actually, being designed for 8/16 colour terminals means there probably wasn't really much of an option).

I do have a few lines in my vimrc to make "///" and "##" appear as greyed out; I use this mostly for "literate programming"-ish type of comments, which don't need to stand out so much. It works very well for me, although for other people it looks like it's a "mistake".

[verve_rat]

I have wondered what a rich text / markup approach to code would look like. Would remove tabs vs spaces if the code included alignment vs scope nesting marks and the reader could format them however they wanted.

[amadeuspagel]

Yes, related: Tables for conditionals. For example, for routing, have a table where the colums are methods and the the rows are paths. Or for keyboard shortcuts, have a table where the the colums are modifier keys and the rows are the modified key.