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.