6 ms·

I’ve always pushed back against the “no comments, they go out of date” sentiment. Comments aren’t milk, they don’t just go off, developers let them go out of d

I’ve always pushed back against the “no comments, they go out of date” sentiment. Comments aren’t milk, they don’t just go off, developers let them go out of date. As others have said, comments should be used to add why, to give context.

randomdata 4y ago
'Why' should be documented in your test suite. Leave a comment too, but don't think you can skip out on the former because you've done the latter.
- citrin_ru 4y ago
  Tests can show what code is expected to do from the point of view of the tests author. They usually have no information why code works this way. Also I've seen more than a few times tests which ossify wrong behavior. Tests need comments too.
  - randomdata 4y ago
    > They usually have no information why code works this way They need to if the the way it works is significant. If it is not significant then the value of a comment becomes somewhat dubious anyway as the code is expendable and doesn't really matter. It is not necessary to understand the program and if it is flawed you're going to rewrite it. Comments can add a lot of value, but there is a line where the value quickly diminishes.
    - still_grokking 4y ago
      How does a test inform you why a function was implemented using algorithm A and not algorithm B which would also do the same? And no matter how clear and clean you write algorithm A, the code will never answer the question why this algo and not another was used. That's the meaning of why here.
      - randomdata 4y ago
        Perhaps a more concrete example would be useful? Nobody cares why you used a given algorithm over another in the general case. If the observation of a unit prompted a need for a specific algorithm – to reduce time complexity, for example – then you have something quite testable to document the choice, so it’s not clear what you are asserting.
        still_grokking 4y ago
        How do you know when it's not "the general case"? Where is this documented? How does a unit test distinguish different algorithm (with of course same big-O characteristics, as obviously otherwise this example would not make any sense in the first place)?
        randomdata 4y ago
        Again, I think we need a concrete example to really understand what you are trying to say. If two algorithms are functionally identical (same results, same space/time complexity, etc.), who cares why? What are you going to gain from knowing more about the choice? I'll give an example. Let's say you need to add 1 to each integer in an array. You could use a for loop, a map function, etc. We'll assume the compiler optimizes each choice to the exact same machine code. What would you like to have documented about the choice?
        wpietri 4y ago
        Exactly my view, too. If a particular algorithm was chosen for, say, performance reasons, then those performance needs should be expressed in a test.
        citrin_ru 4y ago
        An attempt to measure say 5% difference in a tests would likely produce a flaky test which frequent failures would waste team's time. I'm not even starting that to measure this difference in a test one would have to maintain two implementations - slow and faster one and run in a test suite both to have two times to compare. Looks like unnecessary work to me. Enough to run benchmark manually when a decision is being made.
SpeedilyDamage 4y ago
Why must that documentation go inline with the code? There are so many better ways to document design and implementation decisions that don't involve embedding English into source code files. We preach endlessly the idea of orthogonality and abstraction, but then we smash together plain English and Python/C++/Erlang/whatever?
- simonbarker87 4y ago
  If the information in the comment directly relates to the code and is for developers then putting it next to the code makes a lot of sense. Putting it somewhere else just increases the likelihood it will go stale and decreases discoverability of the information.
  - SpeedilyDamage 4y ago
    But that's the point; if it's a "why" doc, it shouldn't be specific to the code, so by virtue of the fact that you feel the need to place it there anyway, it's not really a "why" doc at all, and instead should be resolved by writing clearer code. We agree code should be split into multiple files, why do we suddenly not agree that English should be split as well? Nobody would try to write a file with 30% JS, 50% C++, and 20% Python.
    - alpaca128 4y ago
      Code is very formal and limited in what it can express. The real world tends to be much more chaotic. It is impossible by definition to express some reasons just in code, that's why comments are sometimes necessary. > if it's a "why" doc, it shouldn't be specific to the code Sometimes the "why" is directly connected to that specific part of the code and doesn't concern anything else, or anyone not working on that part of the code. Separating & moving the explanation to another place just makes it less visible exactly where it matters.
      - SpeedilyDamage 4y ago
        If the explanation is directly connected to specific parts of the code, it's not "why", it's "how". "Why" will be true regardless of implementation, "how" won't be. Comments should be less visible, as they distract the coder from understanding what the code actually does with potential lies about what the code ought to do, according to the flawed human who wrote the code. Put the comments elsewhere. We don't put all our code in one file to solve "it needs to be visible!" problems, we shouldn't do it with our docs either, it is not consistent nor is it helpful.

randomdata 4y ago

'Why' should be documented in your test suite. Leave a comment too, but don't think you can skip out on the former because you've done the latter.

citrin_ru 4y ago
Tests can show what code is expected to do from the point of view of the tests author. They usually have no information why code works this way. Also I've seen more than a few times tests which ossify wrong behavior. Tests need comments too.
- randomdata 4y ago
  > They usually have no information why code works this way They need to if the the way it works is significant. If it is not significant then the value of a comment becomes somewhat dubious anyway as the code is expendable and doesn't really matter. It is not necessary to understand the program and if it is flawed you're going to rewrite it. Comments can add a lot of value, but there is a line where the value quickly diminishes.
  - still_grokking 4y ago
    How does a test inform you why a function was implemented using algorithm A and not algorithm B which would also do the same? And no matter how clear and clean you write algorithm A, the code will never answer the question why this algo and not another was used. That's the meaning of why here.
    - randomdata 4y ago
      Perhaps a more concrete example would be useful? Nobody cares why you used a given algorithm over another in the general case. If the observation of a unit prompted a need for a specific algorithm – to reduce time complexity, for example – then you have something quite testable to document the choice, so it’s not clear what you are asserting.
      - still_grokking 4y ago
        How do you know when it's not "the general case"? Where is this documented? How does a unit test distinguish different algorithm (with of course same big-O characteristics, as obviously otherwise this example would not make any sense in the first place)?
        randomdata 4y ago
        Again, I think we need a concrete example to really understand what you are trying to say. If two algorithms are functionally identical (same results, same space/time complexity, etc.), who cares why? What are you going to gain from knowing more about the choice? I'll give an example. Let's say you need to add 1 to each integer in an array. You could use a for loop, a map function, etc. We'll assume the compiler optimizes each choice to the exact same machine code. What would you like to have documented about the choice?
        wpietri 4y ago
        Exactly my view, too. If a particular algorithm was chosen for, say, performance reasons, then those performance needs should be expressed in a test.
        citrin_ru 4y ago
        An attempt to measure say 5% difference in a tests would likely produce a flaky test which frequent failures would waste team's time. I'm not even starting that to measure this difference in a test one would have to maintain two implementations - slow and faster one and run in a test suite both to have two times to compare. Looks like unnecessary work to me. Enough to run benchmark manually when a decision is being made.

SpeedilyDamage 4y ago

Why must that documentation go inline with the code? There are so many better ways to document design and implementation decisions that don't involve embedding English into source code files. We preach endlessly the idea of orthogonality and abstraction, but then we smash together plain English and Python/C++/Erlang/whatever?

simonbarker87 4y ago
If the information in the comment directly relates to the code and is for developers then putting it next to the code makes a lot of sense. Putting it somewhere else just increases the likelihood it will go stale and decreases discoverability of the information.
- SpeedilyDamage 4y ago
  But that's the point; if it's a "why" doc, it shouldn't be specific to the code, so by virtue of the fact that you feel the need to place it there anyway, it's not really a "why" doc at all, and instead should be resolved by writing clearer code. We agree code should be split into multiple files, why do we suddenly not agree that English should be split as well? Nobody would try to write a file with 30% JS, 50% C++, and 20% Python.
  - alpaca128 4y ago
    Code is very formal and limited in what it can express. The real world tends to be much more chaotic. It is impossible by definition to express some reasons just in code, that's why comments are sometimes necessary. > if it's a "why" doc, it shouldn't be specific to the code Sometimes the "why" is directly connected to that specific part of the code and doesn't concern anything else, or anyone not working on that part of the code. Separating & moving the explanation to another place just makes it less visible exactly where it matters.
    - SpeedilyDamage 4y ago
      If the explanation is directly connected to specific parts of the code, it's not "why", it's "how". "Why" will be true regardless of implementation, "how" won't be. Comments should be less visible, as they distract the coder from understanding what the code actually does with potential lies about what the code ought to do, according to the flawed human who wrote the code. Put the comments elsewhere. We don't put all our code in one file to solve "it needs to be visible!" problems, we shouldn't do it with our docs either, it is not consistent nor is it helpful.