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'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.
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.
I prefer faded comments, because some of my code is quite heavily commented. The code itself is what I always read, and I want it to jump out at me. The comments are background info, observations, sometimes wordy descriptions of why things are the way they are, and so on. If I've been away from the code for a while, I'll read the comments to help reestablish the context, refresh my memory of failed experiments, of shortcuts, optimizations, and so on. Most of the time, I don't need to read these comments, so having them faded into the background works for me in every way except for the briefer, more urgent type of comment that SHOULD jump out.
One thing I would like to have is an editor that responded to tags within comments (so it wouldn't be a part of the programming lang syntax, but just a convention used by the programmer) which would apply different colors to different types of comments. I would then use a faded color for wordy background info or comments needed by anyone proposing to change the code but not needed for reading the code, brighter colors for brief comments on the intent of a chunk of code (making the code easier to skim) and maybe a very bright color for WARNING, or FIXME, or STUB-ONLY, or TODO, etc.
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.
Well, typically commenting serves two opposite functions: to removed code from the program while still keeping it nearby and visible (commenting it out), and actual comments. The former should be faded, the latter highlighted. I've tried introducing two types of comments in syntax highlighters before, but it's a pain.
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.
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.
about comments being washed out: in the quest of writing good source code for kids (easy for kids to read, adapt and use) I found that comments should be not only an integral part of the source, but probably not highlighted as a single block, with an uniform color. For kids and beginners, we should have a highlighter for comments that bold words between *, that put some emphasis on titles in comments, that makes function/variable names in comments jump out. Also, we could highlight inline comments (at the end of a line of code, generally frowned upon but potentially useful for beginners and kids) as yellow stickies.
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 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.
What setups are you all using? To me I just associate comments with green, not fadedness. Only exception is Python has an unfortunate case of multiline strings having to be abused for multiline comments but maybe successive # lines would be better anyway, the way IDE's use multiple // instead of a /* */.
Reading through this article, I thought of an idea. What if comments were made using an annotation-like/type input, so you select the lines of code that it pertains to, then enter your message. So whenever the cursor/pointer is within a block of code, the relevant comment/annotation is highlighted/made obvious - ie: like a post-it
This "two types of comments" idea already exists in a limited form as most
editors already display TODO, FIXME and sometimes NOTE in a more visible color.
Extending those could be helpful, this method doesn't break anything in
"incompatible" editors and could be implemented via plugins or config files.
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).
I hate when comments are highlighted. Makes it difficult to read the code as they distract me.
The code is what is hard to read, comments are easy to read. I want help focusing on the code, I don't mind if the highlight structure doesn't help me read the comments as they are more than easy to read already.
That's why quite a few languages don't have block comments. But then it gets very tedious to comment out a section of code without a language aware editor. For me, having comments and strings highlighted is essential.
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.
reply