4 ms·

So train people to write better comments, because although code doesn't lie (questionable as that is since the intent behind the code and what it does doesn't a

So train people to write better comments, because although code doesn't lie (questionable as that is since the intent behind the code and what it does doesn't always align) it can be literally the worst implantation of an algorithm imaginable, and so we teach people how to code. Teaching people how to comment is a skill that's just as important and nothing turns me off a project faster than the "code is its own documentation" mantra.

afarrell 4y ago
How much do you charge to run training sessions on how to write better comments?
- Psyladine 4y ago
  Here's a free method that's twice as much work but produces great results: immediately after composing, for each step and nested step, write a line or two of what its place in the code is for. Write it as though the code is broken and you're following the imaginary line threading through, explained as if to your rubber duck. Then, having written out the business logic map, look at each written step and see if they're just a description of the logic "iterates through file, passes hits onto nextFunc" and you can safely delete those. They're just glue, really, holding processes together. What you'll have left is skeletal comments that are restricted to "we did this because this stackoverflow post gave the solution" as well as those mental maps of the solution in your head, which is really what comments are for, future programmers to grok your state of mind and thus better implement their code changes.
ajross 4y ago
This is misunderstanding the point. Code cannot lie. Reading code (correctly) gives you a correct understanding of the state of the system, no matter how clear or unclear it is. Reading comments only tells you what the person who wrote the comment believed. It does not tell you anything in particular about how the system behaved, you have to trust the other human beings (in general a long succession of them) to have understood it correctly. And any one of you can mess that up. Saying good comments have value is fine. But their ability to lie is unique; code doesn't have that misfeature. You can't make comments lie-free by fiat, for the same reason that you can't train your developers not to write bugs. Given that, IMHO comments have limited value. Don't be a zealot in either direction, but when debugging hard problems, train yourself to ignore the lying comments.
- agalunar 4y ago
  This is a good point, and I'm not arguing with it, but I don't think the words "code cannot lie" are the right way to express it. Code can deceive even if, definitionally, the code states what the computer will do. So code most certainly can lie. [By analogy, you'd still feel lied to if someone told you something that is technically correct but very misleading: "(Me) It's going to rain tomorrow." → tomorrow comes → "(You) It isn't raining today!" → "(Me) It is raining, in Japan. I didn't say it would rain here."] I suppose it depends on whether you're considering what the code communicates to the machine or what it communicates to a person.
  - galangalalgol 4y ago
    How about "code does what it does but comments say what it might have once, and possibly still might do?" You can have your pipeline regression test code, but not comments. Just recently my mentee found some of my code where I had changed the code but not the comment. I'm a horrible human and wasted his time. If that comment hadn't existed the code might have taken a moment to understand but as it was, he wasn't sure which was the intent.
- _AzMoo 4y ago
  While code gives you a correct understanding of the state of the system, it doesn't give you any understanding of why the system is in that state. That's the point from the OP. Code tells you what a system is doing, not why it was designed to be that way. Comments that try and explain what a system is doing can absolutely be wrong and therefore problematic, but there's no way for code to convey the context in which it was implemented a particular way, which is what comments are for. Code without comments only gives half the story. It gives you the what, not the why.
- baby 4y ago
  > Code cannot lie Sure, but it can take you on a freaking trip. Comment your code bro. This whole argument makes me think of C coders who say C is perfectly safe as long as you don’t write bugs.
  - 4y ago
ac50hz 4y ago
+10 It sounds like we have had similar experiences and have come to similar conclusions. Learning to code, learning to comment and learning to log are all ways to learn to communicate and represent a means to risk-reduction and importantly, to cost-reduction.

afarrell 4y ago

How much do you charge to run training sessions on how to write better comments?

Psyladine 4y ago
Here's a free method that's twice as much work but produces great results: immediately after composing, for each step and nested step, write a line or two of what its place in the code is for. Write it as though the code is broken and you're following the imaginary line threading through, explained as if to your rubber duck. Then, having written out the business logic map, look at each written step and see if they're just a description of the logic "iterates through file, passes hits onto nextFunc" and you can safely delete those. They're just glue, really, holding processes together. What you'll have left is skeletal comments that are restricted to "we did this because this stackoverflow post gave the solution" as well as those mental maps of the solution in your head, which is really what comments are for, future programmers to grok your state of mind and thus better implement their code changes.

ajross 4y ago

This is misunderstanding the point. Code cannot lie. Reading code (correctly) gives you a correct understanding of the state of the system, no matter how clear or unclear it is. Reading comments only tells you what the person who wrote the comment believed. It does not tell you anything in particular about how the system behaved, you have to trust the other human beings (in general a long succession of them) to have understood it correctly. And any one of you can mess that up. Saying good comments have value is fine. But their ability to lie is unique; code doesn't have that misfeature. You can't make comments lie-free by fiat, for the same reason that you can't train your developers not to write bugs. Given that, IMHO comments have limited value. Don't be a zealot in either direction, but when debugging hard problems, train yourself to ignore the lying comments.

agalunar 4y ago
This is a good point, and I'm not arguing with it, but I don't think the words "code cannot lie" are the right way to express it. Code can deceive even if, definitionally, the code states what the computer will do. So code most certainly can lie. [By analogy, you'd still feel lied to if someone told you something that is technically correct but very misleading: "(Me) It's going to rain tomorrow." → tomorrow comes → "(You) It isn't raining today!" → "(Me) It is raining, in Japan. I didn't say it would rain here."] I suppose it depends on whether you're considering what the code communicates to the machine or what it communicates to a person.
- galangalalgol 4y ago
  How about "code does what it does but comments say what it might have once, and possibly still might do?" You can have your pipeline regression test code, but not comments. Just recently my mentee found some of my code where I had changed the code but not the comment. I'm a horrible human and wasted his time. If that comment hadn't existed the code might have taken a moment to understand but as it was, he wasn't sure which was the intent.
_AzMoo 4y ago
While code gives you a correct understanding of the state of the system, it doesn't give you any understanding of why the system is in that state. That's the point from the OP. Code tells you what a system is doing, not why it was designed to be that way. Comments that try and explain what a system is doing can absolutely be wrong and therefore problematic, but there's no way for code to convey the context in which it was implemented a particular way, which is what comments are for. Code without comments only gives half the story. It gives you the what, not the why.
baby 4y ago
> Code cannot lie Sure, but it can take you on a freaking trip. Comment your code bro. This whole argument makes me think of C coders who say C is perfectly safe as long as you don’t write bugs.
- 4y ago

ac50hz 4y ago

+10 It sounds like we have had similar experiences and have come to similar conclusions. Learning to code, learning to comment and learning to log are all ways to learn to communicate and represent a means to risk-reduction and importantly, to cost-reduction.