4 ms·

Multiple languages and documentation tools disagree on "comments don't compile/test" fwiw. You definitely can do this, in any language (though some make it muc

by Groxx 4y ago

Multiple languages and documentation tools disagree on "comments don't compile/test" fwiw. You definitely can do this, in any language (though some make it much easier than others). Though I fully admit that automated tests cover nothing related to explanations / things that aren't inherently true or false. Personally I've wanted a way to link code to comments, not just the reverse, so I can change code here and be notified that it affects comments over there, especially during review time (just show every related comment next to the change). It seems literally essential for reliable documentation, but I haven't yet seen it except maybe in WEB (the literate programming language) or similar.

doctor_eval 4y ago
> I fully admit that automated tests cover nothing related to explanations but ... it's the explanations that are important. I mean there are plenty of tools to check that a comment matches a function signature or otherwise describes the properties of a bit of code. But who needs that? At least in a strongly typed language, reproducing the signature or doing anything else that reflects existing code within a comment adds very little. Anyway, I am not arguing against comments. I'm just arguing that they can't somehow magically reduce technical debt. Or that they have anything at all to do with technical debt. Or that the OP made any sense at all.
- Groxx 4y ago
  >but ... it's the explanations that are important. Often, yes! But you can also sometimes mechanically detect when what you're claiming might no longer be true, even if you can't assert the full content. E.g. "X does Y when you Z, so you should QWERTY periodically" -> check X,Y,Z in a slightly relevant way. Maybe have an example QWERTY call that does nothing but compile. If a check like that fails, it means something has changed, which is an ideal time to check that documentation again. If it's not relevant, just fix the test. If it is, it shows why these systems are valuable. (Yes, it's a change-detector test, which everyone hates for good reasons. They work great for things that are important but can't be sufficiently tested though, because the alternative is no automation at all) Plus, the content that's truly hardest to check this way (high level conceptual docs, etc) is also generally the least likely to change in a meaningful way.
  - doctor_eval 4y ago
    This sounds very complicated to me. It seems like a form of meta programming. It doesn’t excite me. If you can work it out from the code, why do you even need the comment? Maybe it’s because I’m old and stupid, but I think that simplicity, efficiency and correctness are virtues, and I find it difficult to see how this qualifies.
    - Groxx 4y ago
      Because people's first interaction with your code is frequently your documentation, not your code. And that sets a lot of expectations, and if it disagrees with reality it impacts how they view your project as a whole. With enough interactions, and in the right areas, extra effort can pay for itself pretty quickly.
dragonwriter 4y ago
> Personally I've wanted a way to link code to comments, not just the reverse, so I can change code here and be notified that it affects comments over there, If your code is separated from comments explaining it so much thag this isn't visibly obvious on review, there’s probabky a bigger problem than “I don’t have a way to link commebts to distant code and vice versa.”
- Groxx 4y ago
  Almost all larger documentation tends to be very separated from the code it's describing, e.g. conceptual docs that cover the whole thing. And fairly often that's significantly more useful information, or in a much more useful format, than the documentation of X on its own.
  - dragonwriter 4y ago
    That makes sense and traceability is useful there. Not what I would describe as “comments”, which shaped my original response, but that’s semantics, not substance.

by Groxx 4y ago

doctor_eval 4y ago

> I fully admit that automated tests cover nothing related to explanations but ... it's the explanations that are important. I mean there are plenty of tools to check that a comment matches a function signature or otherwise describes the properties of a bit of code. But who needs that? At least in a strongly typed language, reproducing the signature or doing anything else that reflects existing code within a comment adds very little. Anyway, I am not arguing against comments. I'm just arguing that they can't somehow magically reduce technical debt. Or that they have anything at all to do with technical debt. Or that the OP made any sense at all.

Groxx 4y ago
>but ... it's the explanations that are important. Often, yes! But you can also sometimes mechanically detect when what you're claiming might no longer be true, even if you can't assert the full content. E.g. "X does Y when you Z, so you should QWERTY periodically" -> check X,Y,Z in a slightly relevant way. Maybe have an example QWERTY call that does nothing but compile. If a check like that fails, it means something has changed, which is an ideal time to check that documentation again. If it's not relevant, just fix the test. If it is, it shows why these systems are valuable. (Yes, it's a change-detector test, which everyone hates for good reasons. They work great for things that are important but can't be sufficiently tested though, because the alternative is no automation at all) Plus, the content that's truly hardest to check this way (high level conceptual docs, etc) is also generally the least likely to change in a meaningful way.
- doctor_eval 4y ago
  This sounds very complicated to me. It seems like a form of meta programming. It doesn’t excite me. If you can work it out from the code, why do you even need the comment? Maybe it’s because I’m old and stupid, but I think that simplicity, efficiency and correctness are virtues, and I find it difficult to see how this qualifies.
  - Groxx 4y ago
    Because people's first interaction with your code is frequently your documentation, not your code. And that sets a lot of expectations, and if it disagrees with reality it impacts how they view your project as a whole. With enough interactions, and in the right areas, extra effort can pay for itself pretty quickly.

dragonwriter 4y ago

> Personally I've wanted a way to link code to comments, not just the reverse, so I can change code here and be notified that it affects comments over there, If your code is separated from comments explaining it so much thag this isn't visibly obvious on review, there’s probabky a bigger problem than “I don’t have a way to link commebts to distant code and vice versa.”

Groxx 4y ago
Almost all larger documentation tends to be very separated from the code it's describing, e.g. conceptual docs that cover the whole thing. And fairly often that's significantly more useful information, or in a much more useful format, than the documentation of X on its own.
- dragonwriter 4y ago
  That makes sense and traceability is useful there. Not what I would describe as “comments”, which shaped my original response, but that’s semantics, not substance.