Sometimes when I describe the development processes that I like, people will say "It sounds like you've adopted agile." This makes me cringe and I usually try to go to some lengths to say that I am most definitely not using agile processes. But the truth is there are many things about agile that I like and find useful: continuous integration, short feature-centered development cycles, maintaining an up to date set of feature requests, a focus on unit testing, etc. But I just can't come to terms with the label agile. As I was reading an article on agile development practices the other day, I realized why this was. People who write about agile development seem to inevitably say things that seem, not to put too fine a point on it, stupid. Here's one that got me all agitated recently:
Any new criteria that surface in the process of elaborating on a user story in code are captured directly in the code, and can be communicated back to the customer later if necessary.
New criteria here is referring to edge and error conditions that come up during coding. And the claim is that the best place to capture these new requirements is directly in the code. I think this is likely the biggest complaint I have about agile. Its practitioners eschew almost all artifacts other than code with a similar underlying justification - that code is the best representation of the logic of an application. In my opinion this is patently false. If you're in a conversation with a developer and ask him how he implemented some specific feature, he is not going to say "First I declared this class called Foo, and then I delcared a method called DoSomething, and then I declared a variable called myVar of type MyType and allocated a new object to assign to it... etc." But that's exactly how code reads. And when requirements change or are added as described in the above quote, you don't want everyone who cares about those changes to have to extract the meaningful information from the details of the code. The customer wants to know what the visible changes will be in their experience of the application. QA wants to know what new boundary cases are appropriate to test for. Yes, you can figure these out from the code, but the code is most definitely not the most effective way to communicate this information.
Furthermore, no matter how much you stare at the code, its not going to tell you the reasons that a particular algorithm was used or the intended patterns of interaction amongst a set of components. Information of this sort is best captured an communicated in design documents, that will likely incorporate artifacts such as sequence diagrams or finite state machine descriptions.
I think people who have adopted the notion that code is the only artifact that matters in software development are making a mistake. It may be the most important artifact, but it is not always the best tool for communicating information about software.