3 ms·

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 comment

by SiVal 14y ago

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.

Cthulhu_ 14y ago
I kinda disagree; if your comments, observations etc don't JUMP OUT AT YOU READ THIS THIS IS IMPORTANT!1one, they're not important, apparently. This also goes for other people's code, really. There is often a difference between code and comments, which causes people to read the code instead of the comments. However, one cause is that comments don't draw the attention because they're often in a dimmed, 'this is not important' color scheme - the other is that there's too much comments that don't add value to the code.
- akkartik 14y ago
  I found this thread fascinating. It seems the more heavily people comment, the less they care about reading comments all the time: http://akkartik.name/blog/2012-11-24-18-10-36-soc http://akkartik.name/blog/2012-11-24-18-10-36-soc. It's almost like there's a law of conservation at work. The law of conservation of human attention. Comments can be used either as background hum or as salient landmarks.
drothlis 14y ago
> context, failed experiments, shortcuts, optimizations, and so on. I think commit messages are the appropriate place for this stuff; I use `git annotate` etc. to find the information when I need it. I often have a 50-line commit message accompanying a one-line code change -- a ratio that would obviously make the code unreadable if all the comments were in-line with the code itself.

by SiVal 14y ago

Cthulhu_ 14y ago

I kinda disagree; if your comments, observations etc don't JUMP OUT AT YOU READ THIS THIS IS IMPORTANT!1one, they're not important, apparently. This also goes for other people's code, really. There is often a difference between code and comments, which causes people to read the code instead of the comments. However, one cause is that comments don't draw the attention because they're often in a dimmed, 'this is not important' color scheme - the other is that there's too much comments that don't add value to the code.

akkartik 14y ago
I found this thread fascinating. It seems the more heavily people comment, the less they care about reading comments all the time: http://akkartik.name/blog/2012-11-24-18-10-36-soc http://akkartik.name/blog/2012-11-24-18-10-36-soc. It's almost like there's a law of conservation at work. The law of conservation of human attention. Comments can be used either as background hum or as salient landmarks.

drothlis 14y ago

> context, failed experiments, shortcuts, optimizations, and so on. I think commit messages are the appropriate place for this stuff; I use `git annotate` etc. to find the information when I need it. I often have a 50-line commit message accompanying a one-line code change -- a ratio that would obviously make the code unreadable if all the comments were in-line with the code itself.