5 ms·

The Problem With Comments

43 points by zacharyvoase 14y ago

iambot 14y ago
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
- olalonde 14y ago
  Yes but this would go against the long tradition of coding with flat text files. See http://stackoverflow.com/questions/160633/why-do-we-still-program-with-flat-files http://stackoverflow.com/questions/160633/why-do-we-still-pr...
  - phpnode 14y ago
    not necessarily, you could do what docco does and assume that comments pertain to the lines of code immediately below them, up until the next comment or the end of the function
  - SquareWheel 14y ago
    Well, we could use a commented syntax and build editor support for it. If HTML, . If C/Java/etc. then the same but with /* */.
    - LaRakel 14y ago
      Tags in comments already exist, most common are probably TODO, FIXME and NOTE.
  - ajuc 14y ago
    Some of us already use metadata in our daily coding - for example commit messages. Recently I've noticed, that I comment less, and instead write more information in commit messages, and do svn blame more often. It's better, because it has more context (you see to which changes this comment is relevant), and is always up-to-date, because you always write fresh commit messages. We have a rule in company, that you have to add task number from JIRA to each commit message, and this alone is a huge improvement - you can always check WHY some change was made).
- nene 14y ago
  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.
danso 14y ago
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.
- qznc 14y ago
  Agreed. Comment should be emphasized by code highlighters. In contrast, keywords should be deemphasized.
- pubby 14y ago
  _Underscores_ and UPPERCASE is all you need for emphasis.
- jrajav 14y ago
  I, for one, don't want anything WYSIWYG in what I'm trusting as my code editor.
- rcxdude 14y ago
  My editor (vim) emphasizes the words 'TODO', 'XXX', and 'FIXME' in comments. I think this is nice behaviour but a more general solution would be better.
jemfinch 14y ago
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.
FrankBooth 14y ago
This misses the greater point, which is that syntax highlighting is a cancer and needs to be cut out.
- khet 14y ago
  Care to explain your point further?
- fuzzix 14y ago
  I'd be interested to hear you elaborate on this. I have always been a fan of syntax highlighting (as long as I have been aware of it - my Speccy lacked it). I am not aware of any negatives.
- ajuc 14y ago
  Now, that's a controversial programming opinion. Can you explain why syntax highlighting is bad?
- progrock 14y ago
  Interesting point. I haven't set up colours in my terminal and it's not the greatest loss in the world, if what you have already is readable code.
jessriedel 14y ago
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.
- jowag 14y ago
  Clojure has this. #_ is used to comment out parts of the code, while ; is used for textual comments
- zacharyvoase 14y ago
  Ah, but the first case shouldn't be faded! I can't tell you how many times I've stumbled across commented-out lines of code, sometimes whole functions or classes, which were accidentally committed because they were too easy to skip over when reviewing the changeset. Again, take the example of the Post-it note: you want to remember to remove it later, not forget about it now.
webreac 14y ago
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. In the article, I have some doubts about the usefulness of the comments of the second example, it is almost paraphrasing the code. 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.
mmahemoff 14y ago
I wouldn't want comments to be emphasised while I'm working with the code. 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. 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.
- mattyod 14y ago
  Agree. When I'm working on a piece of code I want the comments to fade quietly into the background. Some sort of toggle might be useful though. Finish editing your code, hit key combo, comments take centre stage, check they still make sense, return to usual state. Being able to bind this to certain actions such as save or build might be useful too. But not in my face all the time please.
teagoat 14y ago
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.
kbd 14y ago
This is why I always make comments a very visible green in my text editors.
PedroCandeias 14y ago
Comments can be seen as failures to express the meaning of the code clearly[1]. 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. [1] http://butunclebob.com/ArticleS.TimOttinger.ApologizeIncode http://butunclebob.com/ArticleS.TimOttinger.ApologizeIncode [2] http://www.cleancoders.com/codecast/clean-code-episode-5/show http://www.cleancoders.com/codecast/clean-code-episode-5/sho...
- est 14y ago
  > as failures to express the meaning of the code clearly[1]. Or the language, either programming lang or nature lang, is a fail by design?
- qznc 14y ago
  In 99% of cases you are right. Though it is unclear if the tradeoff to use a more expressive language is worth it. For example, compiler optimizations can be quite naturally expressed as graph transformations. However, the implementation is C/C++, so an occasional comment [0] with some ASCII art of the transformation is really helpful. There are cases where I disagree. For example, TODO and FIXME annotations cannot be always replaced by something like NotImplementedException. Sometimes code is so concise that it is not obvious why it solves the problem. Sometimes it is good to state why an "obviously better solution" is not applicable in a special case. [0] https://github.com/MatzeB/libfirm/blob/master/ir/opt/cfopt.c#L256 https://github.com/MatzeB/libfirm/blob/master/ir/opt/cfopt.c...
  - PedroCandeias 14y ago
    I agree. Like everything else, the "comments are failures" statement should not be taken as dogma. That's why I set up textmate to show me comments in a bright color; if they're there, they're there for a reason.
- 14y ago
jhrobert 14y ago
If you dim code instead of comments, you will get some of the benefits of "literate programming". Just try it, it's an interesting experience.
tudorw 14y ago
finally the blink tag finds it's true home :)
D_Guidi 14y ago
are we talking about colorization? or the author doesn't know the difference about code comments and code documentation
- qznc 14y ago
  The problem is most programming languages do not distinguish between comment and documentation. There should be syntax for documentation not convention (comment documents code directly behind).
  - D_Guidi 14y ago
    why java sintax for documentation in comments and .net xml sintax for documentation in comments are invalid? to me, looks that documentation is an effort that most programmers (me included) don't want to do. comments in code are easily to do, instead.
Derbasti 14y ago
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. 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. 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? In the end, I think highlighting keywords like TODO, FIXME or NOTE in comments would be a better solution.
Swizec 14y ago
The problem with comments is people misuse them. Comments should explain decisions, not code. Why 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. And by "you" I mean whomever wrote the code I'm looking at. Usually my past self. I think what I'm saying is that the problem with comments is semantics, not UX.
- maigret 14y ago
  Indeed. And one of the reason for the why, beside just understanding the context and getting a more complete picture, is to allow further developers to add code at the same place because it was meant like that in the original code. Great comments helps to know if a new module should be written, or if the addition fits nicely in the existing picture.
- mmahemoff 14y ago
  This is a problem with education (a lot of introductory textbooks and teachers miss the point). To be fair, people learning to code need different comments from more experienced developers (http://steve-yegge.blogspot.co.uk/2008/02/portrait-of-n00b.html http://steve-yegge.blogspot.co.uk/2008/02/portrait-of-n00b.h...) Another cause is paranoid architects. Lint-testing to ensure even one-line getters and setters are commented. Come on! But it happens in real life.
- qznc 14y ago
  In my opinion the why belongs into the commit message not into a comment. Whys are usually highly context-dependent and you should not include all the context into the comment ("in 2004 we benchmarked A,B and C on such and such a machine and B was fastest"). If it is not context-dependent the solution is obvious and needs no comment.
  - ryanbrunner 14y ago
    Assuming that the solution is always obvious from the code is naive and dangerous. You should always strive to make code speak for itself, but there's occasionally cases that require you to do something unintuitive for some reason or another, and comments serve as a useful warning sign or explanation for future programmers (something that a commit message is uniquely unsuited for) Going through a few files on one of my codebases, here's some of the useful comments that I can find from a quick skim: - Explaining why a dummy argument existed on a method (a third-party library required it) - Explaining why we need to set a weird inheritance column on an ActiveRecord model (we're using 'type' as an actual column) - Calling out some technical debt that could be fixed by someone at some point. All of these are really about calling out why the solution is not obvious.
twelvechairs 14y ago
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).
- sageikosa 14y ago
  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.
nandemo 14y ago
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). AFAIK the way to fix bad or stale comments is do it during code review.
eps 14y ago
There are those who write comments and those who read them. Obviously, former would normally want them to be grayed out and latter might want them to stand out a bit more. So his problem is certainly not the problem, it is barely a problem at all.
acdha 14y ago
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.

43 points by zacharyvoase 14y ago

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

olalonde 14y ago
Yes but this would go against the long tradition of coding with flat text files. See http://stackoverflow.com/questions/160633/why-do-we-still-program-with-flat-files http://stackoverflow.com/questions/160633/why-do-we-still-pr...
- phpnode 14y ago
  not necessarily, you could do what docco does and assume that comments pertain to the lines of code immediately below them, up until the next comment or the end of the function
- SquareWheel 14y ago
  Well, we could use a commented syntax and build editor support for it. If HTML, . If C/Java/etc. then the same but with /* */.
  - LaRakel 14y ago
    Tags in comments already exist, most common are probably TODO, FIXME and NOTE.
- ajuc 14y ago
  Some of us already use metadata in our daily coding - for example commit messages. Recently I've noticed, that I comment less, and instead write more information in commit messages, and do svn blame more often. It's better, because it has more context (you see to which changes this comment is relevant), and is always up-to-date, because you always write fresh commit messages. We have a rule in company, that you have to add task number from JIRA to each commit message, and this alone is a huge improvement - you can always check WHY some change was made).
nene 14y ago
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.

danso 14y ago

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.

qznc 14y ago
Agreed. Comment should be emphasized by code highlighters. In contrast, keywords should be deemphasized.
pubby 14y ago
_Underscores_ and UPPERCASE is all you need for emphasis.
jrajav 14y ago
I, for one, don't want anything WYSIWYG in what I'm trusting as my code editor.
rcxdude 14y ago
My editor (vim) emphasizes the words 'TODO', 'XXX', and 'FIXME' in comments. I think this is nice behaviour but a more general solution would be better.

jemfinch 14y ago

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.

FrankBooth 14y ago

This misses the greater point, which is that syntax highlighting is a cancer and needs to be cut out.

khet 14y ago
Care to explain your point further?
fuzzix 14y ago
I'd be interested to hear you elaborate on this. I have always been a fan of syntax highlighting (as long as I have been aware of it - my Speccy lacked it). I am not aware of any negatives.
ajuc 14y ago
Now, that's a controversial programming opinion. Can you explain why syntax highlighting is bad?
progrock 14y ago
Interesting point. I haven't set up colours in my terminal and it's not the greatest loss in the world, if what you have already is readable code.

jessriedel 14y ago

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.

jowag 14y ago
Clojure has this. #_ is used to comment out parts of the code, while ; is used for textual comments
zacharyvoase 14y ago
Ah, but the first case shouldn't be faded! I can't tell you how many times I've stumbled across commented-out lines of code, sometimes whole functions or classes, which were accidentally committed because they were too easy to skip over when reviewing the changeset. Again, take the example of the Post-it note: you want to remember to remove it later, not forget about it now.

webreac 14y ago

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. In the article, I have some doubts about the usefulness of the comments of the second example, it is almost paraphrasing the code. 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.

mmahemoff 14y ago

I wouldn't want comments to be emphasised while I'm working with the code. 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. 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.

mattyod 14y ago
Agree. When I'm working on a piece of code I want the comments to fade quietly into the background. Some sort of toggle might be useful though. Finish editing your code, hit key combo, comments take centre stage, check they still make sense, return to usual state. Being able to bind this to certain actions such as save or build might be useful too. But not in my face all the time please.

teagoat 14y ago

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.

kbd 14y ago

This is why I always make comments a very visible green in my text editors.

PedroCandeias 14y ago

Comments can be seen as failures to express the meaning of the code clearly[1]. 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. [1] http://butunclebob.com/ArticleS.TimOttinger.ApologizeIncode http://butunclebob.com/ArticleS.TimOttinger.ApologizeIncode [2] http://www.cleancoders.com/codecast/clean-code-episode-5/show http://www.cleancoders.com/codecast/clean-code-episode-5/sho...

est 14y ago
> as failures to express the meaning of the code clearly[1]. Or the language, either programming lang or nature lang, is a fail by design?
qznc 14y ago
In 99% of cases you are right. Though it is unclear if the tradeoff to use a more expressive language is worth it. For example, compiler optimizations can be quite naturally expressed as graph transformations. However, the implementation is C/C++, so an occasional comment [0] with some ASCII art of the transformation is really helpful. There are cases where I disagree. For example, TODO and FIXME annotations cannot be always replaced by something like NotImplementedException. Sometimes code is so concise that it is not obvious why it solves the problem. Sometimes it is good to state why an "obviously better solution" is not applicable in a special case. [0] https://github.com/MatzeB/libfirm/blob/master/ir/opt/cfopt.c#L256 https://github.com/MatzeB/libfirm/blob/master/ir/opt/cfopt.c...
- PedroCandeias 14y ago
  I agree. Like everything else, the "comments are failures" statement should not be taken as dogma. That's why I set up textmate to show me comments in a bright color; if they're there, they're there for a reason.
14y ago

jhrobert 14y ago

If you dim code instead of comments, you will get some of the benefits of "literate programming". Just try it, it's an interesting experience.

tudorw 14y ago

finally the blink tag finds it's true home :)

D_Guidi 14y ago

are we talking about colorization? or the author doesn't know the difference about code comments and code documentation

qznc 14y ago
The problem is most programming languages do not distinguish between comment and documentation. There should be syntax for documentation not convention (comment documents code directly behind).
- D_Guidi 14y ago
  why java sintax for documentation in comments and .net xml sintax for documentation in comments are invalid? to me, looks that documentation is an effort that most programmers (me included) don't want to do. comments in code are easily to do, instead.

Derbasti 14y ago

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. 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. 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? In the end, I think highlighting keywords like TODO, FIXME or NOTE in comments would be a better solution.

Swizec 14y ago

The problem with comments is people misuse them. Comments should explain decisions, not code. Why 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. And by "you" I mean whomever wrote the code I'm looking at. Usually my past self. I think what I'm saying is that the problem with comments is semantics, not UX.

maigret 14y ago
Indeed. And one of the reason for the why, beside just understanding the context and getting a more complete picture, is to allow further developers to add code at the same place because it was meant like that in the original code. Great comments helps to know if a new module should be written, or if the addition fits nicely in the existing picture.
mmahemoff 14y ago
This is a problem with education (a lot of introductory textbooks and teachers miss the point). To be fair, people learning to code need different comments from more experienced developers (http://steve-yegge.blogspot.co.uk/2008/02/portrait-of-n00b.html http://steve-yegge.blogspot.co.uk/2008/02/portrait-of-n00b.h...) Another cause is paranoid architects. Lint-testing to ensure even one-line getters and setters are commented. Come on! But it happens in real life.
qznc 14y ago
In my opinion the why belongs into the commit message not into a comment. Whys are usually highly context-dependent and you should not include all the context into the comment ("in 2004 we benchmarked A,B and C on such and such a machine and B was fastest"). If it is not context-dependent the solution is obvious and needs no comment.
- ryanbrunner 14y ago
  Assuming that the solution is always obvious from the code is naive and dangerous. You should always strive to make code speak for itself, but there's occasionally cases that require you to do something unintuitive for some reason or another, and comments serve as a useful warning sign or explanation for future programmers (something that a commit message is uniquely unsuited for) Going through a few files on one of my codebases, here's some of the useful comments that I can find from a quick skim: - Explaining why a dummy argument existed on a method (a third-party library required it) - Explaining why we need to set a weird inheritance column on an ActiveRecord model (we're using 'type' as an actual column) - Calling out some technical debt that could be fixed by someone at some point. All of these are really about calling out why the solution is not obvious.

twelvechairs 14y ago

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).

sageikosa 14y ago
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.

nandemo 14y ago

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). AFAIK the way to fix bad or stale comments is do it during code review.

eps 14y ago

There are those who write comments and those who read them. Obviously, former would normally want them to be grayed out and latter might want them to stand out a bit more. So his problem is certainly not the problem, it is barely a problem at all.

acdha 14y ago

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.