A Response to Tom Henrich's Document The Why

by Rob Martin on

Highly readable version

On his blog, Tom Henrich[1] calls for better developer documentation[2] on why a design decision was made, rather than just what decision was made. In this post I share my example.

From the source code for a Box.net[3] uploader snippet I wrote in MODX:[4]

/*
 * @name      Down and Dirty Box.net Uploader
 * @author    Rob Martin <rob@qmuxs.com>
 * @copyright (c) 2011 Quintessential Mischief LLC
 * @link      http://www.qmuxs.com
 * @license   GPLv3
 * @version   0.1.0
 *
 * The need for a down & dirty uploader came about after reviewing the
 * box.net PHP library code at https://github.com/boxplatform/box-php.
 * It's just not very good, and some of it is totally borked. It's not
 * even a surprise - I found comments on blog posts dated from February
 * 2008 complaining about a bug (can you call a whole missing function
 * - promised in the docs - a bug?) that has not changed in over three
 * years.
 *
 * I was about to start over. :-( But I did get in touch with Sean ****
 * at Box.net who threw some salt on the open wounds. He let me know
 * that the new PHP library is **just days from release**.
 *
 * And no, he couldn't get it for me. So sorry.
 *
 * The Python code isn't much better, though I haven't read through it
 * as much. However, documentation such as:
 *
 * > """Exception class for errors received from Facebook."""
 *
 * makes me think it might not be. Facebook has nothing to do with this
 * code.
 *
 * **NOTE**: Just so you know, this code doesn't do any of the
 * authentication work. You've gotta do that manually. You need an API key,
 * an auth_token, and a folder ID for where you want the files to land.
 *
 * Here's how:
 *
 * 1. Get a ticket. It'll come back as <ticket>...</ticket>.
 * https://www.box.net/api/1.0/rest?action=get_ticket&api_key={YOUR_API_KEY}
 *
 * 2. Using the ticket, log in.
 * https://www.box.net/api/1.0/auth/{YOUR_TICKET}
 *
 * 3. Request the auth_token. It'll come back as <auth_token>...</auth_token>.
 * https://www.box.net/api/1.0/rest?action=get_auth_token&api_key={YOUR_API_KEY}&ticket={YOUR_TICKET}
 *
 * 4. Get the ID of the folder you want. It'll look like <folder id="xxx" name="this-one".../>
 * https://www.box.net/api/1.0/rest?action=get_account_tree&api_key={YOUR_API_KEY}&auth_token={YOUR_AUTH_TOKEN}&folder_id=0&params[]=nozip
 *
 * So that's the story. Here's the code:
 */

  1. Tom Henrich (@tomhenrich) is a Milwaukee web geek & caffeine fiend. Tom's blog. ↩

  2. Tom's post, Document the Why, not just the How. ↩

  3. Box.net is pretty good at secure cloud storage, and pretty bad at APIs - in my experience anyway. ↩

  4. MODX is a PHP-based content management framework that works well for developers, designers, and content managers. ↩

Talk back to me

You can comment below. Or tweet at me. I'm always open to a good conversation.