8 ms·

Many people think their code is clear. The problem is it is clear often only for the author and sometimes for a limited time even for the author. If anyone else

Many people think their code is clear. The problem is it is clear often only for the author and sometimes for a limited time even for the author. If anyone else start to working with the code questions usually arise. And you can prepare comments for at least some of such questions. In my practice I often see code where useful comments are missing and hours of research required to learn something author for sure knew. Code which has too much comments to me is an imaginary problem - I've seen it at most a couple times in my career and one of them was the code written by a junior developer in a style one can expect in a tutorial or a book. But usually people quickly learn to not add unnecessary comments (and eventually start adding too little of them).

weatherlight 4y ago
Many people think their subjective comments are clear! Code doesn't lie, comments do.
- MrGilbert 4y ago
  Yet, code might not tell the whole story. It's a pitty.
- afandian 4y ago
  I wouldn’t use the word ‘lie’ but plenty of Rails code I’ve seen has mystery effects and hard to follow coupling due to monkey patching and the like. Comments please.
- lordgroff 4y ago
  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.
- saiya-jin 4y ago
  Comments shouldn't be there if they are not maintained in same way code is, meaning there isn't shared understanding in the team about their importance. And important they will be if you actually maintain your code, or somebody else is. Adding few comments means you show respect for their time (and sanity) so they can focus on delivering changes or fixes instead of just grokking your crap. Every time I see 0 comment in complex logic I attribute it to laziness of coder. And of course every time excuse is the same - its self-documenting, you see what its doing etc. But why, what are the effects elsewhere in the system and outside, what part of business needs this is covering, what SLA it tries to cover, what are overall goals etc. can be even impossible to grok from just code itself. World is bigger than just code.
- JohannesH 4y ago
  Comments can lie, but so can code... function Add(int a, int b) { return a - b; } Code can lie in so, so many ways that are much more obscure and confusing than this simple example.
  - JamesBarney 4y ago
    // Adds two numbers together function Add(int a, int b) { return a - b; } is even less clear.
    - rightbyte 4y ago
      Not really. You clearly see that the intent at some point was to add two numbers, and not some fiction about ADD the diagnosis or what ever.
      - ablob 4y ago
        So which one is right, the name of the function (the comment), or it's implementation?
        rightbyte 4y ago
        Rethorical question? You can't know that without looking on how the function is used. You at least know something is strange from the comment.
    - alpaca128 4y ago
      Sure, but I don't think anyone would call this a useful comment - it's exactly the kind of comment which should be avoided. Comments don't need to describe what the code does, but if there's an unexplicable line which handles an obscure edge case you better add a comment or even you won't remember why that line exists 3 months later.
    - TedDoesntTalk 4y ago
      Because comment is out-of-date. That’s technical debt. The comment is not the problem: the developer not updating it is. You wouldn’t leave out-of-date code in a system, it would cause bugs. Why would you leave out-of-date comments? Oh, because you don’t like to write. Your strength is math and code, not writing. Now we get to the heart of the matter and not some ruse like “code is self-documenting.”
- _dain_ 4y ago
  > Code doesn't lie, comments do pi = 3
  - hayst4ck 4y ago
    You can't attach a debugger to the comments and figure out why your code is calculating that the circumfrence of a circle with radius 1 is 6 rather than 6.28... You're proving the point of the person you are responding to. pi = 3 isn't a lie, it's the truth of the program regardless of what any comment says.
    - agalunar 4y ago
      But that is a lie. It's deceptive and misleading. The code states what the computer will do; nobody is contesting that or claiming otherwise. They were pointing out that, although part of what `pi = 3` communicates to a person (that the machine will assign the value 3 to the variable named "pi") is correct, another part of what it communicates (that 3 is close enough to the ratio between a circle's circumference and diameter for the task at hand) may be untrue – and thus a lie. The programs that people work with in their mind are not the programs (the code) that the machine runs. What the machine does is definitely more important in the moment, but the models that live in the heads of people are more important in the long term. The code that the machine runs is just one implementation, a shadow cast by the real thing from one of many angles.
- hooverd 4y ago
  It may not lie, but it can certainly misdirect.
- pkolaczk 4y ago
  Code can lie too. Example: poor naming of classes, functions and variables. A name can tell you it's doing one thing but it can be doing something different.
- citrin_ru 4y ago
  > Code doesn't lie, comments do Code doesn't tell the full story either. And code can contain bugs so one cannot fully trust the code too. If code/comments are out of sync it is likely that someone changed the code and forgot to update comments (which is possible to verify using VCS logs) or it may be that the comment stated the intention right but the code has a bug. Code+comments like a parity check to me - if they agree it is good, if not - I have to investigate if the comment or the code is correct.
jfabre 4y ago
The problem with this argument is that it's implying that there is no such thing as clear code. Sure some people think their code is clear when it is not, but that shouldn't stop you from striving to write clearer code. A long time ago, I had a tendency to write comments to explain code that could be simplified. Refactoring it usually made the comments redundant. Comments are still very useful when the why is unclear.
- TedDoesntTalk 4y ago
  There is a culture that the l33ter the code, the more senior I am. So, many people will never refactor code to make it simpler to read. It affects their ego. In fact, I've seen the opposite: simple code refactored into more complex (not by the original author). The mindset: if it's more complex, it must be better. Java example: rewriting non-stream collections code to use lots of chained streams. Using lambda functions when not needed. Rewriting case labels to use case lambdas. etc.
  - projectazorian 4y ago
    and don’t forget the implicit corollary - if you don’t understand it that just means your IQ is too low, find a job somewhere else noob…
- baby 4y ago
  > Refactoring it usually made the comments redundant That sounds like a nice story
  - jfabre 4y ago
    The fact that you don't believe me blows my mind a little, not going to lie. Maybe this will convince you a little more? https://refactoring.guru/smells/comments https://refactoring.guru/smells/comments
    - grncdr 4y ago
      Don't be too hard on them, they're only a baby after all. More seriously, I agree with you 100%. Many, many, times I've stopped halfway through a writing an explanatory comment and refactored the to make the comment unnecessary. This habit was formed by realizing that most people (including me) don't read comments half as carefully as they read code. So if you want something to be noticed and understood, you better put it in the code.
Arch-TK 4y ago
>Many people think their code is clear. This is true, but if you just get these same people to write more comments, they will also think their comments are clear when they're, in fact, not. I think anyone who is capable of writing clear comments is also equally capable of writing clear code. If I was to suggest investing time in learning some skill, I would suggest learning how to make your code actually clear by getting the right people (with relevant domain expertise, but without experience with the code) to critique it for clarity rather than learning how to make your comments actually clear. Why questions are best answered in architecture documentation, the code itself should be self explanatory (given the architecture documentation) for the most part with specific why comments carefully placed in places where it doesn't make sense to use the architecture documentation. I've read code from various codebases from various companies, large and small. I very rarely see a comment which is genuinely both well placed and useful. From the bits of the linux kernel that I have worked on, I have generally seen pretty good why comments, although I think a lot of them could be shifted into architecture documentation. All in all, when reading code, my default stance is to ignore comments unless I get lost reading the code, then I attempt to read the comments. It has been incredibly rare that I've found unclear code to have clear comments.
- killjoywashere 4y ago
  >if you just get these same people to write more comments, they will also think their comments are clear when they're, in fact, not. I think anyone who is capable of writing clear comments is also equally capable of writing clear code. Think of it more like two lines of bearing. You are far more likely to get an accurate position from two lines of bearing. If you need to understand what past self was thinking, a comment is written in a different mindset than the code. Two different lines of reasoning. Also, I rarely think about writing code for someone else. I write for my future self. And I really want my future self to like my past self. So I strive for clean code and write detailed comments, complete with references.
  - Arch-TK 4y ago
    > Think of it more like two lines of bearing. You are far more likely to get an accurate position from two lines of bearing. I mean in theory yes, but in practice I've usually found comments in such situations to either be missing, outdated or misleading. >If you need to understand what past self was thinking, a comment is written in a different mindset than the code. I don't think I agree with this at all, why would the mindset be different when they were both written at the same time? Like I said, writing good comments requires just as much if not maybe more self awareness of what you're likely to forget in the future as writing clear code. I think if you're at that level where you can successfully muster that, you should spend your time just making your code clearer. In reality I think it's even difficult to muster that requisite introspection skill in the moment and it's usually best left until after you solve the problem (let's say, the next day) to go over the code and check how clear it really is.
baby 4y ago
I agree with you. It’s like having too much doc, or doc so outdated it’s harmful. These are fairy tails. I’d take too much doc or outdated doc any time of the day over no doc/comments.
- ahtihn 4y ago
  Too much documentation, outdated documentation or just plain wrong documentation leads to people simply ignoring it altogether, even the good parts.
  - baby 4y ago
    Who cares if they ignore it. The moment where they get stuck on something then they can check the part that refers to that
rk06 4y ago
IMO, it is better to err on the side of too much comments, as comments are easier to delete than code

weatherlight 4y ago

Many people think their subjective comments are clear! Code doesn't lie, comments do.

MrGilbert 4y ago
Yet, code might not tell the whole story. It's a pitty.
afandian 4y ago
I wouldn’t use the word ‘lie’ but plenty of Rails code I’ve seen has mystery effects and hard to follow coupling due to monkey patching and the like. Comments please.
lordgroff 4y ago
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.
saiya-jin 4y ago
Comments shouldn't be there if they are not maintained in same way code is, meaning there isn't shared understanding in the team about their importance. And important they will be if you actually maintain your code, or somebody else is. Adding few comments means you show respect for their time (and sanity) so they can focus on delivering changes or fixes instead of just grokking your crap. Every time I see 0 comment in complex logic I attribute it to laziness of coder. And of course every time excuse is the same - its self-documenting, you see what its doing etc. But why, what are the effects elsewhere in the system and outside, what part of business needs this is covering, what SLA it tries to cover, what are overall goals etc. can be even impossible to grok from just code itself. World is bigger than just code.
JohannesH 4y ago
Comments can lie, but so can code... function Add(int a, int b) { return a - b; } Code can lie in so, so many ways that are much more obscure and confusing than this simple example.
- JamesBarney 4y ago
  // Adds two numbers together function Add(int a, int b) { return a - b; } is even less clear.
  - rightbyte 4y ago
    Not really. You clearly see that the intent at some point was to add two numbers, and not some fiction about ADD the diagnosis or what ever.
    - ablob 4y ago
      So which one is right, the name of the function (the comment), or it's implementation?
      - rightbyte 4y ago
        Rethorical question? You can't know that without looking on how the function is used. You at least know something is strange from the comment.
  - alpaca128 4y ago
    Sure, but I don't think anyone would call this a useful comment - it's exactly the kind of comment which should be avoided. Comments don't need to describe what the code does, but if there's an unexplicable line which handles an obscure edge case you better add a comment or even you won't remember why that line exists 3 months later.
  - TedDoesntTalk 4y ago
    Because comment is out-of-date. That’s technical debt. The comment is not the problem: the developer not updating it is. You wouldn’t leave out-of-date code in a system, it would cause bugs. Why would you leave out-of-date comments? Oh, because you don’t like to write. Your strength is math and code, not writing. Now we get to the heart of the matter and not some ruse like “code is self-documenting.”
_dain_ 4y ago
> Code doesn't lie, comments do pi = 3
- hayst4ck 4y ago
  You can't attach a debugger to the comments and figure out why your code is calculating that the circumfrence of a circle with radius 1 is 6 rather than 6.28... You're proving the point of the person you are responding to. pi = 3 isn't a lie, it's the truth of the program regardless of what any comment says.
  - agalunar 4y ago
    But that is a lie. It's deceptive and misleading. The code states what the computer will do; nobody is contesting that or claiming otherwise. They were pointing out that, although part of what `pi = 3` communicates to a person (that the machine will assign the value 3 to the variable named "pi") is correct, another part of what it communicates (that 3 is close enough to the ratio between a circle's circumference and diameter for the task at hand) may be untrue – and thus a lie. The programs that people work with in their mind are not the programs (the code) that the machine runs. What the machine does is definitely more important in the moment, but the models that live in the heads of people are more important in the long term. The code that the machine runs is just one implementation, a shadow cast by the real thing from one of many angles.
hooverd 4y ago
It may not lie, but it can certainly misdirect.
pkolaczk 4y ago
Code can lie too. Example: poor naming of classes, functions and variables. A name can tell you it's doing one thing but it can be doing something different.
citrin_ru 4y ago
> Code doesn't lie, comments do Code doesn't tell the full story either. And code can contain bugs so one cannot fully trust the code too. If code/comments are out of sync it is likely that someone changed the code and forgot to update comments (which is possible to verify using VCS logs) or it may be that the comment stated the intention right but the code has a bug. Code+comments like a parity check to me - if they agree it is good, if not - I have to investigate if the comment or the code is correct.

jfabre 4y ago

The problem with this argument is that it's implying that there is no such thing as clear code. Sure some people think their code is clear when it is not, but that shouldn't stop you from striving to write clearer code. A long time ago, I had a tendency to write comments to explain code that could be simplified. Refactoring it usually made the comments redundant. Comments are still very useful when the why is unclear.

TedDoesntTalk 4y ago
There is a culture that the l33ter the code, the more senior I am. So, many people will never refactor code to make it simpler to read. It affects their ego. In fact, I've seen the opposite: simple code refactored into more complex (not by the original author). The mindset: if it's more complex, it must be better. Java example: rewriting non-stream collections code to use lots of chained streams. Using lambda functions when not needed. Rewriting case labels to use case lambdas. etc.
- projectazorian 4y ago
  and don’t forget the implicit corollary - if you don’t understand it that just means your IQ is too low, find a job somewhere else noob…
baby 4y ago
> Refactoring it usually made the comments redundant That sounds like a nice story
- jfabre 4y ago
  The fact that you don't believe me blows my mind a little, not going to lie. Maybe this will convince you a little more? https://refactoring.guru/smells/comments https://refactoring.guru/smells/comments
  - grncdr 4y ago
    Don't be too hard on them, they're only a baby after all. More seriously, I agree with you 100%. Many, many, times I've stopped halfway through a writing an explanatory comment and refactored the to make the comment unnecessary. This habit was formed by realizing that most people (including me) don't read comments half as carefully as they read code. So if you want something to be noticed and understood, you better put it in the code.

Arch-TK 4y ago

>Many people think their code is clear. This is true, but if you just get these same people to write more comments, they will also think their comments are clear when they're, in fact, not. I think anyone who is capable of writing clear comments is also equally capable of writing clear code. If I was to suggest investing time in learning some skill, I would suggest learning how to make your code actually clear by getting the right people (with relevant domain expertise, but without experience with the code) to critique it for clarity rather than learning how to make your comments actually clear. Why questions are best answered in architecture documentation, the code itself should be self explanatory (given the architecture documentation) for the most part with specific why comments carefully placed in places where it doesn't make sense to use the architecture documentation. I've read code from various codebases from various companies, large and small. I very rarely see a comment which is genuinely both well placed and useful. From the bits of the linux kernel that I have worked on, I have generally seen pretty good why comments, although I think a lot of them could be shifted into architecture documentation. All in all, when reading code, my default stance is to ignore comments unless I get lost reading the code, then I attempt to read the comments. It has been incredibly rare that I've found unclear code to have clear comments.

killjoywashere 4y ago
>if you just get these same people to write more comments, they will also think their comments are clear when they're, in fact, not. I think anyone who is capable of writing clear comments is also equally capable of writing clear code. Think of it more like two lines of bearing. You are far more likely to get an accurate position from two lines of bearing. If you need to understand what past self was thinking, a comment is written in a different mindset than the code. Two different lines of reasoning. Also, I rarely think about writing code for someone else. I write for my future self. And I really want my future self to like my past self. So I strive for clean code and write detailed comments, complete with references.
- Arch-TK 4y ago
  > Think of it more like two lines of bearing. You are far more likely to get an accurate position from two lines of bearing. I mean in theory yes, but in practice I've usually found comments in such situations to either be missing, outdated or misleading. >If you need to understand what past self was thinking, a comment is written in a different mindset than the code. I don't think I agree with this at all, why would the mindset be different when they were both written at the same time? Like I said, writing good comments requires just as much if not maybe more self awareness of what you're likely to forget in the future as writing clear code. I think if you're at that level where you can successfully muster that, you should spend your time just making your code clearer. In reality I think it's even difficult to muster that requisite introspection skill in the moment and it's usually best left until after you solve the problem (let's say, the next day) to go over the code and check how clear it really is.

baby 4y ago

I agree with you. It’s like having too much doc, or doc so outdated it’s harmful. These are fairy tails. I’d take too much doc or outdated doc any time of the day over no doc/comments.

ahtihn 4y ago
Too much documentation, outdated documentation or just plain wrong documentation leads to people simply ignoring it altogether, even the good parts.
- baby 4y ago
  Who cares if they ignore it. The moment where they get stuck on something then they can check the part that refers to that

rk06 4y ago

IMO, it is better to err on the side of too much comments, as comments are easier to delete than code