Programming languages are declarative

Why don't people understand this? I've spent a bit of time today on the AzPHP mailing list offering up reasons as to why inline API documentation is a bad thing (private list, so no link).

Think about it - a programming language is a way to declare what you want the computer to do. It's that simple. With a properly written program, all the API docs are doing is hiding the code that tells me exactly what is going on instead of what a programmer once knew - thought in a lot of cases - was going on. And if your code is so complex, or so convoluted that you have to document it in plain-English just to start to understand it, it's time to start refactoring.

This isn't to say I'm not a fan of documentation. I just differ from mainstream PHP in what form I look for. Give me a unit test any day over a three paragraph docblock. The test provides an assumption, the code to prove it, and an example of how I should actually use your code in - get this - real code. It's a win-win-win.

Ok - I'll hop off of my soap box now. Less than 60 hours to go until the pain and torture of this year's Dawn 'til Dusk. I'm waking up at night in a cold sweet sweat thinking about the two climbs this year.