morgan herlocker

RDD

[Readme Driven Development]

I am not the first to coin the phrase, but I am a firm believer in RDD. The basic premise is that you employ the following pattern when developing a module:

readme >> tests >> code >> repeat

It varies a bit from project to project, but my typical flow nowadays is something like this:

1. Describe the behavior of the new function in a readme with a code example.
2. Create a test that is mostly just a copy/paste from the readme code + assertions.
3. Write the actual function, and tinker until it passes the first test.
4. Write a few more tests for any edge cases I can think of.
5. Get the function to pass again.
6. Encounter another edge case; goto 4.

It seems to work pretty well for me anyway.

Why?

The readme is how users first interact with your modules. Before they install your module or call a single function, they are going to look at the readme file and ask "Does this do what I want?" and "Does it do what I want elegantly?". Design your modules around what people are looking for in the readme, then make the code and tests serve that end.

Much like with TDD, the big upside to RDD is that it forces you to do something immensly useful for your project, but which becomes more difficult to implement after the fact. With RDD, you get docs + tests every single time. Also, while TDD forces your code to conform to reasonable tests, RDD forces your code to also conform to reasonable docs. Non tested code usually leads to non testable code, and I think the same is true with docs; non-documented code leads to non-documentable code.

Caveats

On large projects, this could very well be a horrible idea. For one, a readme is a terrible way to store documentation of a huge project. After a certain amount of functionality, it is just going to be too long and difficult to navigate. Also, large and complex projects tend to have lots of moving parts, and it is often difficult to know if the way you are designing the api is even possible before really digging in. This leads to the nightmarish design driven waterfall of the bad ol' days.

Modules

Times are changing though. There is a huge push going on right now towards modular composition-- the idea that functionality can be built a la carte from a hive of distributed modules, rather than from giant frameworks. In this unixy style, a readme should almost always be enough. While that particular holy war is far from settled, modular design has proven itself to be at least one viable option, and one which is particularly well suited for the RDD approach.

3-6-14