> 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.
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