News for hackers. Stuff that matters.
Re:Document the Why by timr on Wednesday March 06, 2013 @06:17PM (#5334727)
"most of your code should be self-documenting, assuming sufficient domain-level knowledge from the reader. If it's self-documenting, comments are redundant."

You're hitting on all the classic lame excuses. Self-documenting code is a myth, invented by lazy coders who would rather crank out code than write documentation, because it's more fun to write code. They're wrong, but they often don't know that they're wrong, because the same people who suck at writing documentation usually suck at reading code.

Clean code is a necessary, but insufficient precondition to understandability. Documentation is essential, because code can only tell you what -- it can't tell you where it should be used, why you should use it, how it should be used, who who should use it or when it's appropriate. And in any case, your code is never as clean or self-documenting as you think it is.

That said, I have no doubt that you're hearing these things from "experienced" coders, because our industry is filled with "experienced" people who suck at what they do. Also, these things are cliches for a reason. They get repeated a lot.

Re:Document the Why by mercurial on Thursday March 07, 2013 @06:07AM (#5337084)
Actually, that's what we use with a rather large codebase, and it works out pretty well. Different tacks for different people, I suppose.
Re:Document the Why by timr on Thursday March 07, 2013 @08:49PM (#5341676)
Not really, no. It's not a matter of opinion.

You can obviously get away with not documenting code, but you don't know what it's costing you. However well things are working out now, I can guarantee that they'd be working better and faster for your team if you spent the time to write good documentation.

Re:Document the Why by mercurial on Friday March 08, 2013 @03:04AM (#5342465)
I'll just leave this here: http://www.martinfowler.com/bliki/CodeAsDocumentation.html

You may think Martin Fowler is one of these "experienced people who suck at what they do", but you're likely to find yourself part of a small minority.