You say “I’ve picked up great code written by other developers that had no comments, and I easily understood exactly how it worked.” That’s exactly right – because most code out there is trivial. I’d challenge you to do that the same with some of my NAT traversal code or multi-source downloading code. I don’t know you, but unless you’re on Jonathon Rosenberg’s team at Cisco or something similar, you’re not going to understand it no matter how clean the code is. Read through 200 pages of RFCs plus the plentiful comments, then you’ve got a shot. Otherwise, you’re just not going to get it. If you think there’s a place my code can be cleaner, I’d love to know, but the sheer complexity of the problem is the issue, not the cleanliness of the code.

This has to do with domains and 80/20 type stuff. The vast majority of code you’ll come across is code most people are familiar with, and comments are pointless. Then there’s that 20% that’s way outside your domain and most people’s domains. That’s where you’re screwed without comments.

You did allude to it, but generally well written code should not have deeply nested loop/if structures. Also with well formatted code it shouldn’t be too difficult to find what loop or if you are currently in. As I said in my later article, these signs are guide lines, not rules written in stone.

When I teach people new to coding I tell them three things. Comment your code, approach your idea from all sides, try to think laterally not uni-laterally and if I can’t read your code, then you can’t read and understand it either.

The problem with comments is that as the code grows and matures, they are not kept up to date. How many times have you seen:

/**
* @param name
* @param manager
* @param dept
*/
public void gargleTheFlooble(String name, String manager) {
…
}

Really helpful comments, those.