3 ms·

I profoundly disagree with that. Comments always end up not following the actual implementation. In this example, "self documenting" the code would be to name t

by molyss 11y ago

I profoundly disagree with that. Comments always end up not following the actual implementation. In this example, "self documenting" the code would be to name the function "unbufferedRead" or something similar that shows that not having a buffer is part of the contract. You make it buffered, you're breaking the contract. Anything else is merely applying temporary (because they'll rot), hidden (because if someone is reading code that calls myVeryWellDocumentedFunction, they won't see the documentation, especially if the function is just incompletely named) and inaccurate (because the only accurate thing is the code) band aids. There's a reason it's said that naming stuff is one of the hardest things in programming.

jlarocco 11y ago
I disagree. Even with the name "ReadOneUnbufferedByteAtATime", the code doesn't (and can't) explain why the author is doing it that way instead of reading multiple bytes at once. If that decision is important then there needs to be a comment explaining it. In my experience, "self documenting" code is brittle and hard to change because nobody knows (or remembers) which implementation details are important and which aren't, so they're afraid to change it. Is it reading a byte at a time for a reason? Or does it not matter and it's just happens to be done that way? There's more to software development than just churning out code, and being disciplined about keeping comments up to date is one of those things that just needs to be done, IMO.
jberryman 11y ago
I agree that naming things well is a great way to document them. However I think that in most of the codebases I've worked on it is quite common for a function/method to do many things some of which are incidental and some necessary, and it would be difficult to include the full set of these in the method's name. (comments also help to make it obvious when a function is, perhaps, too complex and arbitrary). In addition to good naming, strong static types and functional purity help a great deal (but I won't try to evangelize haskell here :)) > ...hidden (because if someone is reading code that calls myVeryWellDocumentedFunction, they won't see the documentation, especially if the function is just incompletely named) what is your proposed alternative? Ideally a function would do the only possible sensible thing imaginable, but that is frequently not attainable. > ...inaccurate (because the only accurate thing is the code) Well when the code doesn't match the spec in the comments, we've found a bug in the code, or a bug in the spec. Either way we can find someone to blame. This is vastly better than finding a bug and not knowing whether the function or the caller should be fixed.

by molyss 11y ago

jlarocco 11y ago

I disagree. Even with the name "ReadOneUnbufferedByteAtATime", the code doesn't (and can't) explain why the author is doing it that way instead of reading multiple bytes at once. If that decision is important then there needs to be a comment explaining it. In my experience, "self documenting" code is brittle and hard to change because nobody knows (or remembers) which implementation details are important and which aren't, so they're afraid to change it. Is it reading a byte at a time for a reason? Or does it not matter and it's just happens to be done that way? There's more to software development than just churning out code, and being disciplined about keeping comments up to date is one of those things that just needs to be done, IMO.

jberryman 11y ago

I agree that naming things well is a great way to document them. However I think that in most of the codebases I've worked on it is quite common for a function/method to do many things some of which are incidental and some necessary, and it would be difficult to include the full set of these in the method's name. (comments also help to make it obvious when a function is, perhaps, too complex and arbitrary). In addition to good naming, strong static types and functional purity help a great deal (but I won't try to evangelize haskell here :)) > ...hidden (because if someone is reading code that calls myVeryWellDocumentedFunction, they won't see the documentation, especially if the function is just incompletely named) what is your proposed alternative? Ideally a function would do the only possible sensible thing imaginable, but that is frequently not attainable. > ...inaccurate (because the only accurate thing is the code) Well when the code doesn't match the spec in the comments, we've found a bug in the code, or a bug in the spec. Either way we can find someone to blame. This is vastly better than finding a bug and not knowing whether the function or the caller should be fixed.