> It seems those who write sparse comments want them to pop out of the screen, and those who comment more heavily like to provide a background hum of human commentary that's useful to read in certain contexts and otherwise easy to filter out.

This has slightly increased the number of comments overall and while I think quality has gone way up, I don’t want them more visible to the point of distraction.

Yep. Put me in the latter camp. If you made my comments more visable it would be highly distracting. Thinking about it like commentary is good because along with WHY comments over WHAT comments, I’ve been making an effort to describe INTENT for future readers (me).

I find that it usually falls down to a 'supra'/'infra' (or meta/within) dichotomy:

- the 'supra-comments' are essentially used as "section headers", "block title / description", i.e. structural markers. It's thus logical to want them standing out, like titles in a text document or section borders in a spreadsheet.

- the 'infra-comments' are the "explicited subtext", "block/line anotation", i.e. substantive but secondary content (usually discussion about the code, which may also be externalized to a spec doc). These are naturally dimmed, because they sit beneath or outside the primary substance, the code (inline or aside, as in text documents and web pages, or even hidden behind a toggle).

In that regard, languages with two syntaxes for comments (eg. block "/* ... */" and end-of-line "// ...") may be formatted by editors respectively "standing out" and "dimmed", giving this two-level comment schema to the developer.

I personally think the 'supra-comment' / structural approach is detrimental to readability (longer, bloat, to me it's ASCII art however you want to spin it), and that problem should be solved by organizing code better (block order, files), choosing more self-explanatory names for everything, and having proper external documentation (however succint, it's not optional and can't be substituted by comments).

In Intelli-j IDE's (WebStorm, PHPStorm, PyCharm etc) I've used a bit of a dirty hack to get as many different comment colours as I need. This involves re-purposing the "to do" highlighting feature.

https://i.imgur.com/EKiVA0X.png

By the way @akkartik, it looks like your imgur link goes to the thumbnail rather than the image :)

Try it now? I fixed it a minute after posting.

Better now.

I really like that idea of highlighting comments in different colours based on the prefix used. Very cool stuff, I will try to work that into my own workflow. Thank you for sharing!

What lispy language is that in the screenshot?

It's Arc, and the program is an ancient prototype of https://github.com/akkartik/mu

Thanks!

Your second image is really blurry :(

Yeah, fixed now.

The _d in the imgur link renders it as a thumbnail, here's the full res version:

https://i.imgur.com/vU783Xo.jpg

Thank you! I actually started out with that link, but it rendered with all the usual Imgur cruft on my phone :/