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.

comments powered by Disqus

Did you know?

I'm a software engineering consultant. This means I can help your company with your software engineering needs:

  • providing temporary manpower for short-staffed software projects

  • helping new software projects get off to a good architectural start

  • improving the performance and reliability of old, legacy software systems

  • doing an important investigation or small project that you've always wanted to do but haven't had time for

Since 1999, I have done software engineering projects for the Canadian government, for Silicon Valley startups, and for established Bay Area companies, for small companies and medium-sized companies, for successful commercial projects and open-source projects. 

Currently accepting small projects. If you have one, email or call me.