The Problem With Comments | Hacker News Reader

The Problem With Comments

blog.zacharyvoase.com

43 pointszacharyvoase49 comments

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.

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.

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

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.

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.

My rule of thumb is that you can't expect people reading the code to go diving into the revision control history. So if a reader of the code needs the information, it goes in a comment. Commit messages justify the change; comments justify the code as it stands. I think these are different kinds of 'why' (though they can certainly often overlap a lot).

I re-taught myself this just the other day.

I had written some code that was hard to understand. So I wrote a comment to explain how it was supposed to work. I come back a couple months later, and guess what? The comment might have made complete sense to the guy who just wrote the code, and therefore already understood how it worked. But to someone who didn't it was completely opaque, and therefore only served to make me more irritated the person who wrote it. (i.e., me a couple months ago.)

So that's why I don't like that style of comments. If the code alone doesn't make sense, then 90% of the time the comments that try to explain it don't make any sense either. Maybe the only situation where this kind of comment is acceptable is if you have to use some hairy dynamic programming algorithm or something like that, in which case the comment should just be the name of the algorithm and a URL for a page that explains it.

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.

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.

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.

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

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

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

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.

I really really hate this practice. It only works for me if (1) the methods pulled out are simple and obvious (usually means they fit recognizable patterns) or (2) the method names are spectacularly more descriptive than they usually are (which is to say, to someone who didn't write the code or to my future self: never). Otherwise, it's like reading a paper or chapter where important comments are left as end-notes. As you are reading along you have to break your train of thought to go find the goddamn thing that you need to help you understand what you are reading. Totally annoying.

It's much better to me if things that are conceptually linked are chunked together. I don't mind scrolling. I don't mind reading. I hate hunting when I am trying to crystallize ideas.

The exception is if there are reusable methods involved. These I always factor out.

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.

Agreed. Comment should be emphasized by code highlighters. In contrast, keywords should be deemphasized.

_Underscores_ and UPPERCASE is all you need for emphasis.

I, for one, don't want anything WYSIWYG in what I'm trusting as my code editor.

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.

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.

Clojure has this. #_ is used to comment out parts of the code, while ; is used for textual comments

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.

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

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.

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.

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

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.

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.

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.

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

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

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

Well, we could use a commented syntax and build editor support for it. If HTML, . If C/Java/etc. then the same but with /* */.

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

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

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.

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 might want them to stand out a bit more. So his problem is certainly not the problem, it is barely a problem at all.

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

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

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

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.

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

Care to explain your point further?

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.

Now, that's a controversial programming opinion. Can you explain why syntax highlighting is bad?

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.

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

Reply on news.ycombinator.com