4 ms·

I don't disagree that public APIs should be well documented. However, I believe it's very easy to forget to update the comments. Especially in scripting languag

by jdmt 13y ago

I don't disagree that public APIs should be well documented. However, I believe it's very easy to forget to update the comments. Especially in scripting languages without type safety. There is little to remind the programmer that arguments were added, types were changed, argument order was modified, behavior was changed, return value was changed, locking behavior was changed, memory allocations were changed, etc. Obviously unit tests should help catch many of these changes. However, it's still up to the coder to remember to change the comments. When you're behind on a deadline or you're juggling 50 different API changes because you're still alpha I'd say it's pretty easy to forget to update a comment. See http://api.jquery.com/jQuery.ajax/ http://api.jquery.com/jQuery.ajax/ if you want an example of on API that could easily have a few typos in it. Who is checking to make sure it's 100% in sync with the code 100% of the time? Not trying to say this example has bugs in the docs but there's a LOT of behavior described that could be out of date.

MaulingMonkey 13y ago
If you're forgetting to update the comments frequently enough to be a problem, you're probably forgetting to update the code that consumes the API too. That quality in general falls by the wayside when you're crunching is no reason to abandon quality altogether.
- dllthomas 13y ago
  Forgetting to change the code that consumes the API means that things don't work, which is visible right away. Forgetting to change the comments will be visible gradually and cruft accumulates. Also, sometimes comments wind up being non-local and just aren't noticed. I agree that in some senses it's "no excuse" but that doesn't mean it won't happen. Documentation that can break visibly when things change is better than static documentation.
  - MaulingMonkey 13y ago
    > Forgetting to change the code that consumes the API means that things don't work, which is visible right away. Oh how do I wish this were the case! > Documentation that can break visibly when things change is better than static documentation. Agreed, but I would not call your average run-of-the-mill unit tests "documentation", nor can all documentation can be programatically tested.
    - dllthomas 13y ago
      > > Forgetting to change the code that consumes the API means that things don't work, which is visible right away. > Oh how do I wish this were the case! It's certainly not always the case, but it's a whole lot more likely to be the case than for unchecked documentation. > > Documentation that can break visibly when things change is better than static documentation. > Agreed, but I would not call your average run-of-the-mill unit tests "documentation", I think "is it documentation" is probably more of a spectrum than any particular threshold, and run-of-the-mill unit tests probably do fall on this spectrum though I'd probably agree that they're not particularly far along it (though that surely varies with the habits of those writing the tests). > nor can all documentation can be programatically tested. As a practical matter, that's certainly currently the case - tooling is not set up for testing documentation, and there are things we'd want to check that would be hard to check in any event. Theoretically also, there are certainly properties that can't be statically demonstrated. I'm not entirely convinced that there's nothing we're interested in that couldn't eventually be got at for the programs we care about, though it's certainly a possibility. Regardless, it seems an ideal worth pushing towards, and if tested documentation is interwoven with untestable documentation such that some conceptual locality is preserved it's less likely (though absolutely still possible, to be sure) that you'll forget to update the other when you're forced to update the one.
einhverfr 13y ago
But the solution is to make sure that the documentation is of a sort that is useful in determining where to fix things. Again, if you have a problem with a function call, the fist question should be "does your call to the function match the documentation?" If it doesn't the first thing you do is change the call to match. Now sometimes one comes to the conclusion that an API is broken, so you have to modify the comments, and then modify the code, but there is a reason to do it in this order. When you modify the comments you are modifying a set of promises you have made to other coders. This allows you to think through how this change is going to work and how it will affect other code out in the wild. Then, when you modify your code, it is going to be better.

by jdmt 13y ago

MaulingMonkey 13y ago

If you're forgetting to update the comments frequently enough to be a problem, you're probably forgetting to update the code that consumes the API too. That quality in general falls by the wayside when you're crunching is no reason to abandon quality altogether.

dllthomas 13y ago
Forgetting to change the code that consumes the API means that things don't work, which is visible right away. Forgetting to change the comments will be visible gradually and cruft accumulates. Also, sometimes comments wind up being non-local and just aren't noticed. I agree that in some senses it's "no excuse" but that doesn't mean it won't happen. Documentation that can break visibly when things change is better than static documentation.
- MaulingMonkey 13y ago
  > Forgetting to change the code that consumes the API means that things don't work, which is visible right away. Oh how do I wish this were the case! > Documentation that can break visibly when things change is better than static documentation. Agreed, but I would not call your average run-of-the-mill unit tests "documentation", nor can all documentation can be programatically tested.
  - dllthomas 13y ago
    > > Forgetting to change the code that consumes the API means that things don't work, which is visible right away. > Oh how do I wish this were the case! It's certainly not always the case, but it's a whole lot more likely to be the case than for unchecked documentation. > > Documentation that can break visibly when things change is better than static documentation. > Agreed, but I would not call your average run-of-the-mill unit tests "documentation", I think "is it documentation" is probably more of a spectrum than any particular threshold, and run-of-the-mill unit tests probably do fall on this spectrum though I'd probably agree that they're not particularly far along it (though that surely varies with the habits of those writing the tests). > nor can all documentation can be programatically tested. As a practical matter, that's certainly currently the case - tooling is not set up for testing documentation, and there are things we'd want to check that would be hard to check in any event. Theoretically also, there are certainly properties that can't be statically demonstrated. I'm not entirely convinced that there's nothing we're interested in that couldn't eventually be got at for the programs we care about, though it's certainly a possibility. Regardless, it seems an ideal worth pushing towards, and if tested documentation is interwoven with untestable documentation such that some conceptual locality is preserved it's less likely (though absolutely still possible, to be sure) that you'll forget to update the other when you're forced to update the one.

einhverfr 13y ago

But the solution is to make sure that the documentation is of a sort that is useful in determining where to fix things. Again, if you have a problem with a function call, the fist question should be "does your call to the function match the documentation?" If it doesn't the first thing you do is change the call to match. Now sometimes one comes to the conclusion that an API is broken, so you have to modify the comments, and then modify the code, but there is a reason to do it in this order. When you modify the comments you are modifying a set of promises you have made to other coders. This allows you to think through how this change is going to work and how it will affect other code out in the wild. Then, when you modify your code, it is going to be better.