Perhaps, but I rather doubt it. Despite the link's claims, comments are noise for precisely the reason GP mentioned. Because comments can (and often do) lie, I only ever read comments after I thoroughly understand what the code is doing. If I already know why it's doing that thing, then the comment is (for me in that moment) superfluous and I'm unlikely to want to bother paying it any attention at all. As such, no matter how distracting you make the color scheme for comments, my brain is eventually going to learn to filter them out by default.
I'm a big fan of comments having a different background color. My code windows are black background, and comments have a very dim magenta background tint to them (with bright green or yellow). I find it relatively easy to either focus on the comments, or ignore them, this way.
When you say "Imagine if comments were displayed like this instead", you realise that you can simply modify the colour scheme of your editor to make it so, right?
And I still don't think that solves your "problem". Even if they appear brighter colours, then it's still very easy to phase them out so that you're just focused on the code. It's only when the comment colours begin to hurt your eyes that I find it distracting.
FWIW comments are quite an important part of reading code, it should not be hidden, at least when comments are used for documentation purposes.
It shouldn't be as prominent as the main code, but should be pretty close to it. Very few color themes get this right.
I enjoyed the article, but if I may express a peeve of mine... In the code listings, can we please not use a syntax coloring scheme that makes the comments nearly unreadable? Especially in blog posts like this, where the code deliberately contains numerous explanatory comments. Such low-contrast text slows down my tired old eyes.
If you don't like to see the comments hide them in your IDE. Most decent IDES let you set the background and foreground colours based on the code.
i.e. I have comments for type /* */ and // set to be grey on a slighgly darker grey so they are pretty much hidden (as they are useless most of the time).
I have colors switched off in most of my editors, but I have found that having a distinction between code and comments (particularly multi-line comments) helps to avoid confusion.
I can just highlight the region if I really want to read it, but mostly, I don't want comments competing for attention in my code and I write a _lot_ of comments in there. It's generally a 1:1 ratio in what I write, so if my comments were bright red my eyes would be burning at the end of the day.
I love this article. Nice re-framing of color choices.
This makes me think it would be nice to have at least two functionally distinct comment types: remarks (to be visually hilighted), and temporarily disabled code (to be visually suppressed). I suppose comment lines (remarks) and comment blocks (code) could be used for this, but as the author points out this would need to be a widely adopted convention.
I hope you don't mind a piece of constructive criticism about the web page but: the syntax coloring scheme you're using makes the comments nearly invisible. Code comments are useful, and therefore should be easily readable, IMHO.
Agreed. If I'm looking for comments, the washed out look is easy to pick up. Also. many people don't or can't follow clean code.
Could you imagine the mess if you were writing an API that required JSdoc with the author's proposed highlighting scheme? Or Golang's enforcement of comments on public functions?
Yep. Not only it generates useless comments, for me it is actually easy to read the code itself, than the generated comments in this case. I don't know neither language nor framework they use, still it is completely readable.
Most of the time I deleted my own comments after things become more obvious - I hate 'moving parts' in my code
The trick is to highlight comments with bright & contrast fg/bg color combo that hurts your eyes (it also serves to say 'hi i'm comment, i'm important, but delete me when u understand me')
Actually what hes done in the example works a bit more subtly than his description. The brightness of the comments (yellow) is similar to the background (white), which allows you to read the code by itself (squint and the code stands out, whilst the comments fade into the background). The same thing wouldn't work nearly so well if, for instance, you had white text on a black background (with yellow comments).
Maybe we should have a second kind of comment, for code you don't want to be run. Then it can be highlighted (or the opposite) differently and not pollute real comments.
Rather than visual noise, it makes comments sections immediately recoognizable as such. Think of page-long comments containing code samples. The tool support is trivial, and you can always run a simple regex to fix it up.
Line comments in general have the advantage that they can be trivially nested, and the nesting be immediately recognizable as such. For any new programming language, I would only support line comments, for that reason.
Now that would take the gray comments a step further by making them completely invisible :)
I can't really see the benefit of hunting the comments from your code with cursor. It definitely would make it even more unlikely that comments aren't updated when code is changed.
reply