3 ms·

My paycheck begs to differ! But really, comments are one way to mislead in code. If a comment is made that incorrectly states the intent of code, it's undenia

My paycheck begs to differ! But really, comments are one way to mislead in code. If a comment is made that incorrectly states the intent of code, it's undeniable that this is harmful to the readability of the code.

shizzy0 13y ago
What's pay got to do with it? See http://michaelochurch.wordpress.com/2012/11/18/programmers-dont-need-a-union-we-need-a-profession/ http://michaelochurch.wordpress.com/2012/11/18/programmers-d... Comments may mislead yes, but that's a problem with any sufficiently expressive language, and code is one such language: code can mislead. The functionality required of the code may be only half-implemented, then that code is misleading. That code may work for certain easy cases, but it may be harmful to your understanding of what functionality is actually required. It's easy to see why we prioritize code over comments, why we prioritize the mechanisms over the specifications. It's because code can have some manner of automatic verification, and we're too harried to look into the comments, to do code review. Deadlines abound. We can't stop work and say, no, we can't do this under these time constraints without sacrificing a minimum level of quality, specifically because we're not treated like an actual profession with the clout or the responsibility that comes with such a thing.
- diminoten 13y ago
  We don't prioritize code over comments because it can be automatically tested, we prioritize code over comments/spec because the code is what gets executed. And I can say "this can't be done under these time constraints" at my job. If you can't, then you're not being taken seriously because of some other reason, not because you're a programmer.
  - mannykannot 13y ago
    If that's the way you work, then your employer has made a mistake.
  - mannykannot 13y ago
    My previous comment ("If that's the way you work, then your employer has made a mistake") was ambiguous, and actually illustrates a point regarding comments (and documentation in general). Like that comment, the short verb phrases that make up source code cannot always express the intent of the programmer (extreme 'self-documenting code' advocates think otherwise, but their experience with simple programs and algorithms doesn't generalize.) In such cases, comments are a good way to explain a design issue that is not obvious. Who cares about these things, which don't change the code? Anyone who needs to understand the code, which includes anyone working on it, including its original author - writing a brief explanation of a tricky point can help you spot mistakes before you compile or test, or even before you write the code. The goal is to produce correct code, not just code, and the one thing that is faster than continuous testing is avoiding mistakes in the first place. FWIW, I think the idea that comments need to be complete sentences is silly. Sentences can be as wrong, ambiguous, misleading or uninformative as simple phrases.
mannykannot 13y ago
I am curious as to how you think this should inform the way we program. You could also say 'coding errors are harmful to the usefulness of programs', but that gives us essentially no insight into how to do things better.
- diminoten 13y ago
  You need code to run code. You don't need comments to run code.
  - mannykannot 13y ago
    Do you realize that this observation does not answer the question? There are multiple possible suppositions as to what, if anything, you are implying, so why don't you stop beating about the bush and state clearly the message you are trying to convey?
    - diminoten 13y ago
      Your style of commenting is not what this site is about. Go back to Reddit, I'm done.

shizzy0 13y ago

What's pay got to do with it? See http://michaelochurch.wordpress.com/2012/11/18/programmers-dont-need-a-union-we-need-a-profession/ http://michaelochurch.wordpress.com/2012/11/18/programmers-d... Comments may mislead yes, but that's a problem with any sufficiently expressive language, and code is one such language: code can mislead. The functionality required of the code may be only half-implemented, then that code is misleading. That code may work for certain easy cases, but it may be harmful to your understanding of what functionality is actually required. It's easy to see why we prioritize code over comments, why we prioritize the mechanisms over the specifications. It's because code can have some manner of automatic verification, and we're too harried to look into the comments, to do code review. Deadlines abound. We can't stop work and say, no, we can't do this under these time constraints without sacrificing a minimum level of quality, specifically because we're not treated like an actual profession with the clout or the responsibility that comes with such a thing.

diminoten 13y ago
We don't prioritize code over comments because it can be automatically tested, we prioritize code over comments/spec because the code is what gets executed. And I can say "this can't be done under these time constraints" at my job. If you can't, then you're not being taken seriously because of some other reason, not because you're a programmer.
- mannykannot 13y ago
  If that's the way you work, then your employer has made a mistake.
- mannykannot 13y ago
  My previous comment ("If that's the way you work, then your employer has made a mistake") was ambiguous, and actually illustrates a point regarding comments (and documentation in general). Like that comment, the short verb phrases that make up source code cannot always express the intent of the programmer (extreme 'self-documenting code' advocates think otherwise, but their experience with simple programs and algorithms doesn't generalize.) In such cases, comments are a good way to explain a design issue that is not obvious. Who cares about these things, which don't change the code? Anyone who needs to understand the code, which includes anyone working on it, including its original author - writing a brief explanation of a tricky point can help you spot mistakes before you compile or test, or even before you write the code. The goal is to produce correct code, not just code, and the one thing that is faster than continuous testing is avoiding mistakes in the first place. FWIW, I think the idea that comments need to be complete sentences is silly. Sentences can be as wrong, ambiguous, misleading or uninformative as simple phrases.

mannykannot 13y ago

I am curious as to how you think this should inform the way we program. You could also say 'coding errors are harmful to the usefulness of programs', but that gives us essentially no insight into how to do things better.

diminoten 13y ago
You need code to run code. You don't need comments to run code.
- mannykannot 13y ago
  Do you realize that this observation does not answer the question? There are multiple possible suppositions as to what, if anything, you are implying, so why don't you stop beating about the bush and state clearly the message you are trying to convey?
  - diminoten 13y ago
    Your style of commenting is not what this site is about. Go back to Reddit, I'm done.