The problem with comments is people misuse them. Comments should explain decisions, not code. <i>Why</i> are you doing this? Not how, I can see how from your code if it isn't crappy. If I can't see how from the code, you should improve the code.<p>And by "you" I mean whomever wrote the code I'm looking at. Usually my past self.<p>I think what I'm saying is that the problem with comments is semantics, not UX.
I wouldn't want comments to be emphasised while I'm working with the code.<p>The real reason comments are de-emphasised is not because someone thinks they're less important, but because you use code in two different modes. In one mode, you're getting an overview and might want comments for that. In another mode, you're working on the code and are so immersed in it, you don't need the comments. That's why many environments support comment expanding/collapsing.<p>There are more sophisticated things imaginable for code representation, like where it is held in a relational DB or something, but simple flat text files tend to work best, so we're stuck with the reality of having two show a dumb sequence of characters in these two different modes. So to me, code is like those pictures with two different meanings ("Boring Figures"). You choose to see it with or without the comments. And de-emphasised text works for that.
Comments are dimmed because half of the time, they are commented code and half of the other half, they are useless or wrong comments. 3/4 of the time, dim is the good choice.<p>In the article, I have some doubts about the usefulness of the comments of the second example, it is almost paraphrasing the code.<p>When I was developing, the number of lines of code, comments, blank were computed. Projects having this kind of "quality" indicators had generally a lot of annoying comments.
Comments can be seen as failures to express the meaning of the code clearly[1].<p>I recently began experimenting with a coding style in which blocks of more than 5 lines get refactored into methods with self explanatory names and arguments and so far it's working quite well. Code reads like prose[2]. Couple that with proper TDD, and comments get very rare indeed. Those that remain are there for very good reasons and yes, should probably be displayed in a very contrasting color by the IDE. As far as I can tell, Uncle Bob is right.<p>[1] <a href="http://butunclebob.com/ArticleS.TimOttinger.ApologizeIncode" rel="nofollow">http://butunclebob.com/ArticleS.TimOttinger.ApologizeIncode</a><p>[2] <a href="http://www.cleancoders.com/codecast/clean-code-episode-5/show" rel="nofollow">http://www.cleancoders.com/codecast/clean-code-episode-5/sho...</a>
The tendency to dim comments, rather than emphasize them, is an excellent point. It'd be even nice if there were a markdown like syntax, common across all major favors of commenting, that allowed simple emphasis of words.
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've repeatedly complained to Github (the source of the syntax highlighting sample with the dimmed-out comments) that the comments are nigh impossible to read, despite being the one part of the source code designed for me and only me to read.
Your editor can display comments in whatever way you want. The flipside is that it's an individual setting (as opposed to, say, source control settings).<p>AFAIK the way to fix bad or stale comments is do it during code review.
As far as regular comments go, this is probably true. But then, comments serve more than one purpose. Not all comments are there for those special edge cases.<p>For example, what about docstrings? That is, comments that contain documentation that is supposed to be sufficient even if the code is not available? I daresay those should not be emphasized.<p>Or what about instructional code that is written to be read by people with less than perfect knowledge of the programming language or problem domain?<p>In the end, I think highlighting keywords like TODO, FIXME or NOTE in comments would be a better solution.
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).
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?<p>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.
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
I've increasingly been wondering whether it'd be better to have editors split comments sideways ala docco: there's been a huge trend towards wider screens and using that space seems intriguing, particularly if it avoided discouraging longer comments when a design decision wasn't simple.
There are those who write comments and those who read them. Obviously, former would normally want them to be grayed out and latter <i>might</i> want them to stand out a bit more. So his problem is certainly not <i>the</i> problem, it is barely a problem at all.