, ScanIAm wrote

*snip*

Yes.  As I said, you leave the figuring out for after you've left.

Comments don't magically make crappy code more understandable in my opinion. I've seen plenty of well commented code that I could not get my head around.

And really I stress this because it's important: "comments can lie". You can read a comment that tells you something that is patently wrong. And it's EASY to write comments that lie. IIRC there is no such thing as a unit test for comments. They don't compile either. Just considering that, you should be scared of them. Considering that I consider comments borderline dangerous.

*snip*

http://blog.mpathirage.com/2010/08/15/comments/

Read the whole thing.  Even he admits it isn't possible.

And while I applaud and encourage the "Agile is Pefection" concept, I'm adult enough to recognize that reality doesn't always work that way.

I've read his whole book on clean code. He does believe that sometimes comments are unavoidable, but not because it's okay to write comments in clean code. It's never okay.

Robert Martin understands that nobody is perfect and tools/languages aren't perfectly descriptive either. Sometimes it's beyond the programmers capability to write clean code (ie. code that can not be understood in it's own right), and he must use a comment to explain what he is doing. As a crutch for unclean code.

That's the important thing to remember: comments are ALWAYS a crutch for unclean code. Sometimes you need crutches but you don't need to actively beat yourself to death by littering a code base with them.