Documentation Driven Development

Okay, not really.

But you know how you don’t commit code unless it’s got tests?

Do that same thing for documentation. That most languages we work in generate some kind of docs automatically from source make this easy — your docs are in source control, in fact your docs are (usually) right next to the code, or can be.

Just like you wouldn’t make a commit without tests for the feature you added or changed being in that same commit, don’t make a commit without some at least minimal docs for the feature you added or changed being in that commit — at LEAST a one liner above the method documenting any side effects or return value expectations/invariants. And sometimes this is enough.  Maybe a sentance or two in the class header advertising the existence of the method if it’s important.  And yeah, sometimes a ‘guide’ narrative is called for, if you can swing it.

Yeah, sometimes you can let this slide (just like sometimes you probably let tests slide too), but it should be the goal.

Especially if your code is open source used by lots and lots of people. Yeah, I’m looking at you Rails — Rails documentation over the past few years got a lot better than it used to be, but it’s starting to slip again.


Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )


Connecting to %s