This is a fable bad programmers tell to themselves to justify their intellectual laziness.
No real world code is simple and elegant enough that you don't need to think through the complex invariants of the code, consider would be relevant to future maintainers, and then write it down.
How large can 'data' be? Is there a limit? Will the send be chunked into multiple dispatches if 'data' is too large? Is that opaque to the caller? Does it matter to the caller?
If none of those questions are answered, the caller must delve into the sendDataWithTimeout() implementation to figure out the answers, and it is impossible to modify sendDataWithTimeout() without possibly breaking assumptions callers make based on what they've assumed from implementation of sendDataWithTimeout().
This applies equally well to blocks of code within a function that accept input and provide output. It helps to be able to reason about them as atomic units, without necessarily paying the code/maintenance cost of hoisting them into independent functions.
> This applies equally well to blocks of code within a function that accept input and provide output. It helps to be able to reason about them as atomic units, without necessarily paying the code/maintenance cost of hoisting them into independent functions.
This seems rather... crazy. Functions serve this purpose, avoiding creating function while still trying to think of your code block as a function is just absurd. Extract the function, if it deserves a comment and has parameters, and isn't an anonymous method for use with a higher order function, then make a real function out of instead of polluting the parent function with its implementation details.
The overhead of this additional function you're so worried about is nothing compared to the overhead of the mess that results by not extracting it. Your strategy favors long functions, yuk yuk yuk.
Listening to you talk, I'm horrified by the thought of what your code must look like; I bet your functions often require use of the scroll bar.
> (A) assume the comments are correct and skip reading what the code does?
Yes, unless I was working on that particular piece of code. There's often far too much code in a code base to waste time reading it all, and reading the comments can provide quick understanding.
> The first seems awfully risky to me and poor advice to any programmer trying to write solid code.
Why? Bad code is bad code. Writing bad comments (or no comments) means you're writing bad code. Don't write bad code, and then write documentation to help yourself think through why it's not bad code, and tests to both help you think through it, and verify that it's not bad.
> No real world code is simple and elegant enough that you don't need to think through the complex invariants of the code
in my experience working on enterprise biz apps the opposite is true. comments are what you do when you don't have time to make the code explicitly match your mental model of the proper solution. "don't have time" is a bit of a euphemism, as a lot of people don't realize that it is possible to write code that explicitly matches our mental model of the solution, but whatever.
here's an example: python lib requests vs urllib2. one of these could probably use a comment. the other is self evident. https://gist.github.com/973705
In my experience working on enterprise applications, the worst code is that written by programmers that think they're so smart -- and their code is so good -- that it doesn't need comments.
No programmers are that smart, and no programmers are that good. I'm innately distrustful of any argument that's predicated on "be smarter than average".
If someone writes poor code, what makes you think they will be able to write quality comments? The reality is that if you are poor at expression, you are generally going to be poor at it in all mediums.
I'm inclined to agree, but it is the generally accepted attitude in the industry.
Programming is design, but programmers are routinely taught that they do not need to care about design. The de-facto training facility for the industry, a CS degree, rarely goes into artistic endeavours (naturally, but students rarely take it upon themselves to fill their skill gaps after graduation). In fact, it is the status quo for programmers to joke about how poor their design skills are.
Good programmers go over and above and study not only the theory behind programming, but also design. Until we start promoting that programmers must be good designers, the problem will continue.
If this is the intended meaning then I disagree. The problem is that the kind of code most of us write isn't pure implementations of algorithms backed by formal proofs. In that case the code is the documentation because it is an expression of a mathematical description of something.
The code most of us write is a hodgepodge of business logic, frontend code, and a bunch of glue to make it all work together. In the case of business logic context is highly important. Just looking at the code doesn't convey the whole story or the "why" this code does what it does. In this specific case comments are the difference between saying "we don't know why this works," and "according to BUG-#### we need to send the counterparty this field as a logon credential otherwise their system behavior is undefined."
No real world code is simple and elegant enough that you don't need to think through the complex invariants of the code, consider would be relevant to future maintainers, and then write it down.