Self Documenting code is a serious oxymoron. Sadly too many people do this and create disasters when they quit and leave the rest of us to pick up the pieces. One persons “self documenting code” is another person’s headache / garbage.

I agree with your statement about documenting routines. Here is where you should describe the function.

Lets be honest. I think most people avoid comments because they hope to create a program that they alone will understand and have a lifetime job maintaining. Or they are so ashamed at their lack of ability that they don’t want to spell out the awful crap they write so that others can pick it apart.

I don’t know about that. Having return values that indicate one of success or failure is one thing but you’re opening a can of worms with that. When there are more than one reasons of failure and each failure event has data attached to it, it becomes way more complex using return values to indicate this rather than exceptions.

Here’s some links:

http://today.java.net/pub/a/today/2003/12/04/exceptions.html
http://www.onjava.com/pub/a/onjava/2006/01/11/exception-handling-framework-for-j2ee.html

Additionally the source code is only self-documenting to someone who has a good knowledge of the programming language that the source code is written in. However it is often the case that the person who has the best understanding of the problem space (be they a business analyst, end client or whatever) does not have sufficient developer experience to be able to read the code itself.