3 ms·

Sometimes possible, but not always. An executable test is good for documenting what a piece of code should do, but not always entirely sufficient for documenti

Sometimes possible, but not always. An executable test is good for documenting what a piece of code should do, but not always entirely sufficient for documenting why.

jsight 8y ago
Exactly, and in the pathological case it ends up documenting the why incorrectly and the code is still wrong.
- pure-awesome 8y ago
  Yes, but this is hardly an argument against using comments. There will always be a pathological case. The question is what approach will increase your chances of success, what's least likely to lead to problems, what's the cost-risk-benefit tradeoff etc. Comments detailing the intent of a non-obvious function are valuable for maintainers wanting to figure out what's happening in the code. They are written in human-oriented business-oriented language, so they don't take effort to read. The intent of the code should not change that often. If they diverge from the code, the effort of changing them should be small enough to be worth it. Ideally they should be treated as important and if they are wrong it should be picked up in the code-review. Comments detailing just the description of what a function does, by contrast, are not valuable, since that information can be deduced from the code itself. Every time the function changes, the comment will change. Reading them is as much effort as reading the code, so if they diverge it won't be picked up as easily. There are always exceptions to these kinds of guidelines, of course, but this at least gives motivation for why I think comments should be used in this way.
couchand 8y ago
Though I agree that it's not always possible, I would contest your second point, at least for the majority of testing effort. Sure, a unit test might just document what code is doing, because that's really the only why. But most testing effort should go into describing the why more carefully, which must be done at a higher level, as close as possible to how a user will interact with the thing. Writing tests at the user's level and not getting bogged down in minutia requires careful factoring of the what and why. The what changes frequently, so if most of your tests are overly focused on the what, you will constantly need to update them as the code changes. The why changes much more slowly, so if your tests are written to exercise the why rather than the how, they will be resilient to changes in the implementation. Of course, the what has to be somewhere, and when it changes there will need to be corresponding test updates, but these shouldn't require updating each individual test. The what can be kept cleanly factored out into helpers, leaving the why to remain as the essence of each test.

Sometimes possible, but not always. An executable test is good for documenting what a piece of code should do, but not always entirely sufficient for documenting why.

jsight 8y ago

Exactly, and in the pathological case it ends up documenting the why incorrectly and the code is still wrong.

pure-awesome 8y ago
Yes, but this is hardly an argument against using comments. There will always be a pathological case. The question is what approach will increase your chances of success, what's least likely to lead to problems, what's the cost-risk-benefit tradeoff etc. Comments detailing the intent of a non-obvious function are valuable for maintainers wanting to figure out what's happening in the code. They are written in human-oriented business-oriented language, so they don't take effort to read. The intent of the code should not change that often. If they diverge from the code, the effort of changing them should be small enough to be worth it. Ideally they should be treated as important and if they are wrong it should be picked up in the code-review. Comments detailing just the description of what a function does, by contrast, are not valuable, since that information can be deduced from the code itself. Every time the function changes, the comment will change. Reading them is as much effort as reading the code, so if they diverge it won't be picked up as easily. There are always exceptions to these kinds of guidelines, of course, but this at least gives motivation for why I think comments should be used in this way.

couchand 8y ago

Though I agree that it's not always possible, I would contest your second point, at least for the majority of testing effort. Sure, a unit test might just document what code is doing, because that's really the only why. But most testing effort should go into describing the why more carefully, which must be done at a higher level, as close as possible to how a user will interact with the thing. Writing tests at the user's level and not getting bogged down in minutia requires careful factoring of the what and why. The what changes frequently, so if most of your tests are overly focused on the what, you will constantly need to update them as the code changes. The why changes much more slowly, so if your tests are written to exercise the why rather than the how, they will be resilient to changes in the implementation. Of course, the what has to be somewhere, and when it changes there will need to be corresponding test updates, but these shouldn't require updating each individual test. The what can be kept cleanly factored out into helpers, leaving the why to remain as the essence of each test.