4 ms·

"Every comment here is redundant. The textual decoration attempts to assert its own importance, adding two non-semantic lines to every comment. And indeed the e

by timr 13y ago

"Every comment here is redundant. The textual decoration attempts to assert its own importance, adding two non-semantic lines to every comment. And indeed the eye is drawn to the useless comments instead of the code. So, after looking at these useless comments all day, what do we do? We use our syntax highlighter to turn them off!" Is it really such a burden to scan a few comments? Come on. The real problem here is that most developers are total brats about reading code. They'd rather cut off their hand than read anything, and once you're in that mindset, anything that you can latch onto is the target for excessive, self-affirming hostility about the stupidity of the author: those comments are just useless! The idiot who wrote this code must be terrible! I now feel slightly more justified in re-writing everything! Given that developers almost never write comments for anything, I'd rather see someone erring on the side of over-commenting. If I see code that has been commented in that way, and I see that the other methods are well-commented, I know that the developer was probably more careful than the person who wrote no comments at all. I'm more likely to trust the code. Moreover, having your editor insert a comment on every new method is really a best practice -- it gets you in the habit of documenting, because you always have that empty comment template, staring at you.

dfan 13y ago
The real problem in that case is that every function declaration turned into 1 line of declaration, 2 lines of comments, 1 line of whitespace, and 2 lines of "comment whitespace". Blowing up the amount of vertical space that code takes up by a factor of six really is a problem. I think the main meta-issue with comments is that they live in the same space as the code at all. For a while I've thought that they might be better as marginal notes like other commentary often is, which is why I'm excited about ideas like Marginalia (http://gdeer81.github.io/marginalia/ http://gdeer81.github.io/marginalia/), though I haven't tried it myself.
- timr 13y ago
  "Blowing up the amount of vertical space that code takes up by a factor of six really is a problem." Is it? Maybe I'm the only person who has never experienced this problem. Especially with editor code folding, method nav, tags, etc., vertical space is almost never an issue for me. (Horizontal space, OTOH, is the bane of my existence...) Marginalia is interesting, though...thanks for the pointer!
- nitrogen 13y ago
  There are a few solutions: - Use a folding editor. - Buy a bigger monitor. - Use a split-pane editor with two+ views of one file (e.g. Vim). - Write shorter functions.
- Mithaldu 13y ago
  That is not the real problem, it's just an exacerbation of the underlying issue: Comments must never describe WHAT the code does, but WHY it does so. The code itself should clearly describe what it does. If you need comments for that, you've written unreadable code and need to write more readable code. Comments that describe the what just absolve the programmer from doing that, while putting more effort on everyone coming after them. A comment that describes why a certain bit of code does something, describe something that the code itself cannot and thus help everyone.
  - Pacabel 13y ago
    That is a very academic way of looking at it. In practice, it's often good to have comments that explain what the code is doing, even if the code itself is quite understandable. It can be a lot quicker to read and understand a one-sentence English description than it can be to read 10+ lines of good code. If the code in question generally has accurate comments of this nature, then working with this code becomes far easier. And then there are always those cases where rather poor code was written in the first place, it lacked comments, and then a maintenance programmer needs to figure out what it does in order to make some changes to it. Real-world constraints prevent the code from being completely rewritten, but adding comments explaining what it does can be invaluable for anyone else who will ever need to deal with the code.
    - Mithaldu 13y ago
      It is not academic at all, but utterly practical. In your example of a 10+ line code block that is preceded by a comment, the correction is to extract that code into a subroutine and name it accordingly and maybe write actual documentation* for the usage of said subroutine. Your second example is valid, though i have to admit i've not once been in that situation in my years of work, despite often working with legacy code, and suspect it's fairly rare. * Note here that comments are not documentation, these are two different entities, one being aimed at the maintainer of a library, the other aimed at the user.
krig 13y ago
You couldn't possibly be more wrong. Comments that describe the code and not the intent are terrible for obvious and clear reasons: They are not checked by the compiler, and they are not checked at runtime. There are no assertions that flag when the comment has gone out of date. Comments that talk about what the implementation does are virtually guaranteed to be wrong. This is simple fact. The thing comments can do that code is less good at is express abstract intent, and they should be saved for that. However, more powerful and expressive languages can express much of that in code as well, and thus even such comments can often be removed. Look. What is code, and what are comments? Code is stating some fact that is expressed in a well-defined grammar. It can be both 1) read by machines, and 2) read by humans. Code says something specific, and it has a specification or at least a reference implementation which describes the exact meaning of what the code says. Sure, it can be wrong, which simply means that it says something other than what the author intended, but what it says is well specified. Comments, on the other hand, have no restrictions at all. They can be written in any language. They can be fragments of sentences or multiple paragraphs. If they do follow some structure, it is not enforced unless by some external tool, in which case the comment is, in fact, code as input to that tool, and the complexity of the program has increased by an order of magnitude as it is now written in multiple languages at once. Comments are worse than useless and should always be seen as the last resort. Wherever there is a comment, there should be a language deficiency that prevented whatever needed to be said from being said in the language itself. If there is no such thing, and the comment merely states what the code already says in a well-defined manner, the comment is wrong and should be removed.
- timr 13y ago
  It's fairly ironic that you've spent so many words re-iterating the argument that "code should be self-documenting". You're right that comments don't maintain themselves, though. That's the job of a programmer, and if the programmer isn't doing their job, they probably shouldn't be working on a project with other people.
  - TelmoMenezes 13y ago
    > It's fairly ironic that you've spent so many words re-iterating the argument that "code should be self-documenting". It would be ironic if it was being argued that natural languages are bad. But that is not what's being argued, and the author of that comments was not trying to convey an algorithm to you. > That's the job of a programmer, and if the programmer isn't doing their job [...] This is puritanism. Just because it's work, doesn't mean it's useful.

by timr 13y ago

dfan 13y ago

The real problem in that case is that every function declaration turned into 1 line of declaration, 2 lines of comments, 1 line of whitespace, and 2 lines of "comment whitespace". Blowing up the amount of vertical space that code takes up by a factor of six really is a problem. I think the main meta-issue with comments is that they live in the same space as the code at all. For a while I've thought that they might be better as marginal notes like other commentary often is, which is why I'm excited about ideas like Marginalia (http://gdeer81.github.io/marginalia/ http://gdeer81.github.io/marginalia/), though I haven't tried it myself.

timr 13y ago
"Blowing up the amount of vertical space that code takes up by a factor of six really is a problem." Is it? Maybe I'm the only person who has never experienced this problem. Especially with editor code folding, method nav, tags, etc., vertical space is almost never an issue for me. (Horizontal space, OTOH, is the bane of my existence...) Marginalia is interesting, though...thanks for the pointer!
nitrogen 13y ago
There are a few solutions: - Use a folding editor. - Buy a bigger monitor. - Use a split-pane editor with two+ views of one file (e.g. Vim). - Write shorter functions.
Mithaldu 13y ago
That is not the real problem, it's just an exacerbation of the underlying issue: Comments must never describe WHAT the code does, but WHY it does so. The code itself should clearly describe what it does. If you need comments for that, you've written unreadable code and need to write more readable code. Comments that describe the what just absolve the programmer from doing that, while putting more effort on everyone coming after them. A comment that describes why a certain bit of code does something, describe something that the code itself cannot and thus help everyone.
- Pacabel 13y ago
  That is a very academic way of looking at it. In practice, it's often good to have comments that explain what the code is doing, even if the code itself is quite understandable. It can be a lot quicker to read and understand a one-sentence English description than it can be to read 10+ lines of good code. If the code in question generally has accurate comments of this nature, then working with this code becomes far easier. And then there are always those cases where rather poor code was written in the first place, it lacked comments, and then a maintenance programmer needs to figure out what it does in order to make some changes to it. Real-world constraints prevent the code from being completely rewritten, but adding comments explaining what it does can be invaluable for anyone else who will ever need to deal with the code.
  - Mithaldu 13y ago
    It is not academic at all, but utterly practical. In your example of a 10+ line code block that is preceded by a comment, the correction is to extract that code into a subroutine and name it accordingly and maybe write actual documentation* for the usage of said subroutine. Your second example is valid, though i have to admit i've not once been in that situation in my years of work, despite often working with legacy code, and suspect it's fairly rare. * Note here that comments are not documentation, these are two different entities, one being aimed at the maintainer of a library, the other aimed at the user.

krig 13y ago

You couldn't possibly be more wrong. Comments that describe the code and not the intent are terrible for obvious and clear reasons: They are not checked by the compiler, and they are not checked at runtime. There are no assertions that flag when the comment has gone out of date. Comments that talk about what the implementation does are virtually guaranteed to be wrong. This is simple fact. The thing comments can do that code is less good at is express abstract intent, and they should be saved for that. However, more powerful and expressive languages can express much of that in code as well, and thus even such comments can often be removed. Look. What is code, and what are comments? Code is stating some fact that is expressed in a well-defined grammar. It can be both 1) read by machines, and 2) read by humans. Code says something specific, and it has a specification or at least a reference implementation which describes the exact meaning of what the code says. Sure, it can be wrong, which simply means that it says something other than what the author intended, but what it says is well specified. Comments, on the other hand, have no restrictions at all. They can be written in any language. They can be fragments of sentences or multiple paragraphs. If they do follow some structure, it is not enforced unless by some external tool, in which case the comment is, in fact, code as input to that tool, and the complexity of the program has increased by an order of magnitude as it is now written in multiple languages at once. Comments are worse than useless and should always be seen as the last resort. Wherever there is a comment, there should be a language deficiency that prevented whatever needed to be said from being said in the language itself. If there is no such thing, and the comment merely states what the code already says in a well-defined manner, the comment is wrong and should be removed.

timr 13y ago
It's fairly ironic that you've spent so many words re-iterating the argument that "code should be self-documenting". You're right that comments don't maintain themselves, though. That's the job of a programmer, and if the programmer isn't doing their job, they probably shouldn't be working on a project with other people.
- TelmoMenezes 13y ago
  > It's fairly ironic that you've spent so many words re-iterating the argument that "code should be self-documenting". It would be ironic if it was being argued that natural languages are bad. But that is not what's being argued, and the author of that comments was not trying to convey an algorithm to you. > That's the job of a programmer, and if the programmer isn't doing their job [...] This is puritanism. Just because it's work, doesn't mean it's useful.