Why doc is important in code

At Ning, my teammate Chris Brewer and I like to document our code thoroughly: JavaDoc-style doc for all our PHP/JS classes, methods, method parameters, and instance variables.

There are two very good reasons for documenting everything, even non-public functions:

1. Developers come and go. If you need to do some work on some unfamiliar code written by someone 5 years ago (maybe even yourself), you will appreciate the doc he left saying what the class or method is supposed to do. For example,

class Bundle extends XG_Model {

doesn't help much, whereas

/**
 * A collection of Entry objects. For example, a blog is a Bundle of BlogEntry
 * objects. Equivalent to a "widget instance" in the old WWF world.
 */
class Bundle extends XG_Model {

gives you more clues.

2. The doc is a loose contract that often hints at the assumptions for each method parameter. For example,

* @param integer $start  (optional) index of the first object to return

tells you that the code doesn't expect you to set $start (it is "optional"). If we wanted to change the function to make $start a required parameter, we would know that some callers may not have set $start, and we would know to double-check all callers to make sure.

These are little things, but they make a developer's life easier.

Underscore.php

I found a cool library called Underscore.php that I added to our codebase at Ning. Underscore is a PHP port of the popular Underscore.js library. It has handy functions for working with arrays and objects.

Philosophy books

I have been feeling a bit intellectually starved of late, not having read seriously in a while. I came across this great list of Peter Kreeft's recommended philosophy books, and I would like to do some slow reading of some of those, starting with the Book of Ecclesiastes. I would like to choose titles that have some connection to my Catholic faith - so Plato and Aristotle for example. "On Beauty" also sounds promising.