Readme driven development

In response to the recent craze of test-driven development, I thought I would propose an alternative that I find much more appealing: readme driven development.

By writing a readme first, you can get the ideal version of your product down on paper. You can describe the ins and outs, without having to spend time thinking about how to write tests to test the various parts. When I’m excited to create a new piece of functionality or an entirely new product, I don’t want to spend those precious first adrenaline-filled hours writing monotonous tests. However, going in without a plan is usually a bad idea and will lead to poorly written, poor functioning code. A readme is that middle ground. Its easier to describe in English what I want the product to do then it is to write a bunch of tests.

Writing a readme instead of tests also allows you to focus on only planning the important things. At the beginning of the development cycle, you shouldn’t be worrying about things such as the minimum length of a string, and you definitely should not be spending those first few excitement fueled hours writing a test to ensure the string never gets too small. While this certainly may be important, it is the job for a test later on, not one that is written before the product itself.

While test cases encourage this nit-picking behavior, readmes do not. Readmes encourage describing your overall project, not specific details like minimum string length. This allows you to map out the features you want the product to have, then implement those, and avoid all the small-scale stuff that isn’t relevant during initial development. After the new feature is working as-per the readme, that is when tests should come into play. That’s when you can worry about the length of that string, or the ever important equality of those two numbers.

Recently with one of my projects, I decided it was about done and ready for to be public, so I decided to write the readme for GitHub. As I wrote it, I didn’t write it to reflect the current version of the product, but instead the perfect version. As a result, when I was done writing the readme, I went back and changed the things that didn’t fit the description in the readme. It made the product a little closer to my idea of perfection. If I had done that at the beginning, I am sure parts of the code would be even better than they are right now.

Readme -> Development -> Test coverage.

Its going to be big.

Edit: After writing this post, I became aware that there is already another article out there proposing nearly the exact same thing: