6 ms·

This is probably not a popular view, but I don't really understand why comments are viewed by some people as a bad thing. I agree that useless, redundant comme

This is probably not a popular view, but I don't really understand why comments are viewed by some people as a bad thing. I agree that useless, redundant comments are not helpful. But that doesn't mean all comments are useless. I don't agree that well-written code never needs comments either. Reading the code tells you what it does. It doesn't always tell you why it's there. Digging through version control comments seems to me a last-ditch effort to figure out what some code is doing. If the project had any significant history you could be digging through hundreds of commit messages. Why not just put a 1-liner comment above that line and save every subsequent developer the hassle of wondering what the heck that seemingly useless line does..?

geoka9 13y ago
> This is probably not a popular view, but I don't really understand why comments are viewed by some people as a bad thing. Probably the same people think that well-written code does not need comments at all. That may be so, but well-written code is hard to come by. While this rock-star macho attitude is aplenty.
- ghayes 13y ago
  And to be perfectly honest, well written code might not stay well written as project circumstances change. Thus, documentation that can be updated often makes life easier going forward.
  - tetha 13y ago
    And even worse, sometimes code can't be well-written once you start interfacing with third party software with quirky shenanigans. We got quite some comments flying around such as "In case you are wondering: yes, this call is necessary, or this and that situation will propagate through these two libraries and break with this obscure, unhelpful error message. If you ever change this, look at those documentation files for unobvious, scary testcases to look at".
- mistermann 13y ago
  > Probably the same people think that well-written code does not need comments at all. That may be so, but well-written code is hard to come by. While this rock-star macho attitude is aplenty. Not only that, but I speculate that those holding such opinions are usually young, well above average programmers who therefore work exclusively on brand new projects - many of them have literally never experienced the nightmare of maintaining and extending some crap code written in the most clever and obscure way possible by someone similar to themselves. Hell, a lot of them likely don't stick around long enough to make major modifications to their own code.
  - geoka9 13y ago
    Yes, it's easy (and fun) to write clever code that is unmaintanable. It's much harder to write code that is simple. To me, people who can do that day in, day out are true rock-stars of programming.
HeyLaughingBoy 13y ago
Exactly this. I found myself thinking WTF as I read the article. Maybe I'm showing my age, but the project I just switched from (and still have to consult on from time to time) was started in the late 90's and probably won't be retired for at least 10 more years. I have found myself not just looking through version control history to understand the change history of a file to find a bug, but tracking it over multiple version control systems as the project matured.
_delirium 13y ago
Is that actually a widespread view? I though at least post-1970 or so, it was pretty standard practice to comment liberally. Going all the way to Knuth-style literate programming hasn't caught on, I'll admit, but I didn't think wall-of-code was widely admired anymore either.
- StavrosK 13y ago
  I disagree with "liberally", as there's a cost associated with commenting (they have to be maintained and people have to spend time to read them), but I'm certainly of the opinion that judiciously commenting is very useful.
- jakejake 13y ago
  It's been a while since I've seen a discussion on code comments here on HN but I have noticed in the past that there's a vocal group who are fairly passionate against code comments. I was actually expecting a wave of downvotes to my original comment.
KMag 13y ago
Exactly this, with the addition that there are actually three things I want to see when reading code, only one of which can often be elegantly expressed without comments. I usually want to see (1) what the code does (2) what the code is intended to do and (3) why the code is intended to work that way. Usually only the first can elegantly and most easily be expressed in code. For instance, I read a performance-critical function that would stop processing data and return early in an obscure corner case, but performed better than the best way I could think of to handle the obscure corner case. There were at least 3 possibilities: (1) the author made a mistake (2) for reasons I couldn't see, the corner case was impossible or (3) for reasons I couldn't see, the consequences of mishandling the corner case were never as bad as I thought they could be and the performance gain was worth it. I had to look up the revision history, call up the author and ask him which it was. It turns out the author had missed the corner case, but I try to as rarely as possible assume I'm smarter/more insightful than the original author.
tsiki 13y ago
I think it has something to do with the idealistic view of "pure, well-written" code. There's something appealing about a code base consisting of only code, not comments. But in my very subjective experience, I've noticed that the more programming experience people have under their belts, the more likely they are to appreciate commenting as a tool among other tools to make your code readable.
- jakejake 13y ago
  I think that's a very good point and it seems to me the spirit of that argument is "write code that is so clean that it doesn't need comments." Or the inverse of that could be "if your code needs a lot of comments then it probably isn't very clean." So I think that is a good mentality in as much as it keeps you thinking and writing clean code. But, I think it's also rather presumptuous to assume everything will be clear to others. Also as you say - once you've had to stick around and maintain a few applications, you really appreciate a thoughtful programmer who put in some comments that saved you a few hours. And you start to loath the rock-star who came in for 6 months and wrote a bunch of code using the fad-of-the-moment design pattern without commenting anything.

geoka9 13y ago

> This is probably not a popular view, but I don't really understand why comments are viewed by some people as a bad thing. Probably the same people think that well-written code does not need comments at all. That may be so, but well-written code is hard to come by. While this rock-star macho attitude is aplenty.

ghayes 13y ago
And to be perfectly honest, well written code might not stay well written as project circumstances change. Thus, documentation that can be updated often makes life easier going forward.
- tetha 13y ago
  And even worse, sometimes code can't be well-written once you start interfacing with third party software with quirky shenanigans. We got quite some comments flying around such as "In case you are wondering: yes, this call is necessary, or this and that situation will propagate through these two libraries and break with this obscure, unhelpful error message. If you ever change this, look at those documentation files for unobvious, scary testcases to look at".
mistermann 13y ago
> Probably the same people think that well-written code does not need comments at all. That may be so, but well-written code is hard to come by. While this rock-star macho attitude is aplenty. Not only that, but I speculate that those holding such opinions are usually young, well above average programmers who therefore work exclusively on brand new projects - many of them have literally never experienced the nightmare of maintaining and extending some crap code written in the most clever and obscure way possible by someone similar to themselves. Hell, a lot of them likely don't stick around long enough to make major modifications to their own code.
- geoka9 13y ago
  Yes, it's easy (and fun) to write clever code that is unmaintanable. It's much harder to write code that is simple. To me, people who can do that day in, day out are true rock-stars of programming.

HeyLaughingBoy 13y ago

Exactly this. I found myself thinking WTF as I read the article. Maybe I'm showing my age, but the project I just switched from (and still have to consult on from time to time) was started in the late 90's and probably won't be retired for at least 10 more years. I have found myself not just looking through version control history to understand the change history of a file to find a bug, but tracking it over multiple version control systems as the project matured.

_delirium 13y ago

Is that actually a widespread view? I though at least post-1970 or so, it was pretty standard practice to comment liberally. Going all the way to Knuth-style literate programming hasn't caught on, I'll admit, but I didn't think wall-of-code was widely admired anymore either.

StavrosK 13y ago
I disagree with "liberally", as there's a cost associated with commenting (they have to be maintained and people have to spend time to read them), but I'm certainly of the opinion that judiciously commenting is very useful.
jakejake 13y ago
It's been a while since I've seen a discussion on code comments here on HN but I have noticed in the past that there's a vocal group who are fairly passionate against code comments. I was actually expecting a wave of downvotes to my original comment.

KMag 13y ago

Exactly this, with the addition that there are actually three things I want to see when reading code, only one of which can often be elegantly expressed without comments. I usually want to see (1) what the code does (2) what the code is intended to do and (3) why the code is intended to work that way. Usually only the first can elegantly and most easily be expressed in code. For instance, I read a performance-critical function that would stop processing data and return early in an obscure corner case, but performed better than the best way I could think of to handle the obscure corner case. There were at least 3 possibilities: (1) the author made a mistake (2) for reasons I couldn't see, the corner case was impossible or (3) for reasons I couldn't see, the consequences of mishandling the corner case were never as bad as I thought they could be and the performance gain was worth it. I had to look up the revision history, call up the author and ask him which it was. It turns out the author had missed the corner case, but I try to as rarely as possible assume I'm smarter/more insightful than the original author.

tsiki 13y ago

I think it has something to do with the idealistic view of "pure, well-written" code. There's something appealing about a code base consisting of only code, not comments. But in my very subjective experience, I've noticed that the more programming experience people have under their belts, the more likely they are to appreciate commenting as a tool among other tools to make your code readable.

jakejake 13y ago
I think that's a very good point and it seems to me the spirit of that argument is "write code that is so clean that it doesn't need comments." Or the inverse of that could be "if your code needs a lot of comments then it probably isn't very clean." So I think that is a good mentality in as much as it keeps you thinking and writing clean code. But, I think it's also rather presumptuous to assume everything will be clear to others. Also as you say - once you've had to stick around and maintain a few applications, you really appreciate a thoughtful programmer who put in some comments that saved you a few hours. And you start to loath the rock-star who came in for 6 months and wrote a bunch of code using the fad-of-the-moment design pattern without commenting anything.