The documentation is the code. Duh!

Let me start by saying that I tend to agree with most of the common tenants of extreme/agile programming, as well as test-driven development.

However, this stuff about “the code is the documentation” has some serious drawbacks. For example, my fellow code monkeys and I are writing some stuff against a framework that has some 400 classes. When we run our build scripts and get errors outside of our own code, we have absolutely no idea what we're looking at when we look at those existing classes, in part because we aren't entirely sure what the code is supposed to do. Looking at the unit tests are almost less helpful.

The notion that nearly a hundred developers (when this project hits full speed) are supposed to know and figure out what these 400 classes do on their own isn't realistic or efficient. Furthermore, with all of this technology, we sure as hell shouldn't need to rely on person-to-person storytelling techniques that tribal cultures were using hundreds of years ago. Come on, you've played the “telephone” game, right?

I think even in an agile environment, you still need some basic blueprints to get around, or your new hires are going to run for the exits.