Travis Swicegood

Programming languages are declarative

Published On
April 11 2007
Author
Travis Swicegood

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.

About

Travis Swicegood is a professional programmer and owner of Domain51, a web development company with a focus on non-profits, NGOs, and online activists. He doesn't change the world, he supports those who do.

He has personal a focus on web applications, performance, and stability; is author of Pragmatic Version Control using Git; and working on his second book. He has been using PHP; since '99 and still remembers how revolutionary PHP 4 was, but can't remember why. He's a TDD, open-source, and open government advocate—sometimes called a zealot—and lurker on many an open-source project mailing list when not learning other programming; languages; for fun, exploring his surroundings on bike, or tasting his latest kitchen and home-brew creations.

Contact
Around the Internet