What is Well-Commented Code?

WannaBeGeekGirl queries: "What exactly is well-commented code anyway? Can anyone suggest resources with insight into writing better comments and making code more readable? After about six years in the software development industry I've seen my share of other people's code. I seem to spend a lot of time wishing the code had better (sometimes _any_) comments. The comments can be frustrating to me for different reasons: too vague, too specific, incoherent, pointing out the obvious while leaving the non-obvious to my imagination, or just plain incorrect. Poorly or mysteriously named variables and methods can be just as confusing. In a perfect world everyone would follow some sort of coding standards, and hopefully those standards would enforce useful comments. Until then, any suggestions for what you, as a programmer, consider to be good/useful/practical comments? Any suggestions for what to avoid? Also, I usually work with C++ so any resources/comments specific to that language would be too."

Comments

Does the spec include screen shots?

[yerricde]

if you can't write the user-manual from the spec then the spec is incomplete.

So you're saying the specification should include screen shots of the finished app on all platforms? What about the names of the owners of all trademarks used in the manual?

Not only could you comment out the program structure document so that the compiler would ignore it -- but you ended up with absolutely accurate and comprehensive documentation built into that source.

Unless, when it comes time to maintain the software, some new hire goes in and changes the code without updating the comments in parallel. Then the code and the spec have fallen out of sync. It will happen.

If you're smart and use good tools you can selectively collapse and expand the in-source documentation

What free editor do you suggest?