"You are describing micro-readability, IMO. I've read lots of code where it was clear what each line of code did, but not at all clear what the end result was,

"You are describing micro-readability, IMO. I've read lots of code where it was clear what each line of code did, but not at all clear what the end result was, or why it was being done." No. Unless you consider chunks of 90-100 lines of code to be micro, in which case I think your point is irrelevant, you have effectively defined the terms of the debate such that you've argued yourself right out of it. Also, your terms are silly, if looking at 100 lines of code is micro, what is macro? Looking at 10,000 lines of code simultaneously? you must have a very generous boss to have bought you such a large monitor!!! The test of readability which I administered was at the unit level, not the individual line of code level. I think you make a good minor point about why. The why is incredibly important. This is something that people who say they don't bother with comments because comments get out of date blah blah blah get wrong. A comment is not there to say what you are doing, a comment is there to say why you are doing it, or what you want to achieve. Also, comments should be kept up to date. It costs practically nothing to slip in a: // bugfix for bug #127; forgot to snorgle the barr just above your change