
The Problem With Comments - zacharyvoase
http://blog.zacharyvoase.com/2012/09/07/comments/
======
Swizec
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.

~~~
qznc
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
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.

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

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

------
PedroCandeias
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>

[2] [http://www.cleancoders.com/codecast/clean-code-
episode-5/sho...](http://www.cleancoders.com/codecast/clean-code-
episode-5/show)

~~~
qznc
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...](https://github.com/MatzeB/libfirm/blob/master/ir/opt/cfopt.c#L256)

~~~
PedroCandeias
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.

------
danso
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
Agreed. Comment should be emphasized by code highlighters. In contrast,
keywords should be deemphasized.

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

~~~
zacharyvoase
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.

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

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

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

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

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

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

------
iambot
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
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-
pr...](http://stackoverflow.com/questions/160633/why-do-we-still-program-with-
flat-files)

~~~
SquareWheel
Well, we could use a commented syntax and build editor support for it. If
HTML, <!-- COMMENT: lorem ipsum -->. If C/Java/etc. then the same but with /*
*/.

~~~
LaRakel
Tags in comments already exist, most common are probably TODO, FIXME and NOTE.

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

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

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

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

~~~
qznc
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
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.

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

~~~
fuzzix
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.

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

